Troubleshooting
Resolve common issues with the Walrus CLI, configuration, and network connectivity.
How to use the latest binary
Before undertaking any other steps, make sure you have the latest walrus binary. If you have multiple versions in different locations, find the binary that is actually used with which walrus.
How to check for old hardware or incompatible VMs
The standard Ubuntu binary causes problems on certain old hardware and in certain virtualized environments. If you experience errors like Illegal instruction (core dumped), install the ubuntu-x86_64-generic version instead, which is compiled to be compatible with almost all physical and virtual x86-64 CPUs.
How to verify the Sui network configuration
If you get an error like the specified Walrus system object does not exist, make sure your wallet is set up for the correct Sui network (Mainnet or Testnet) and you use the latest configuration.
How to update to the latest Walrus configuration
Walrus Testnet is wiped periodically and requires updating to the latest binary and configuration. If you get an error like could not retrieve enough confirmations to certify the blob, you are probably using an outdated configuration pointing to an inactive Walrus system. Update your configuration file with the latest configuration and make sure the CLI uses the intended configuration.
When you set RUST_LOG=info, the walrus client binary prints information about the configuration it uses when starting execution, including the path to the Walrus configuration file and the Sui wallet.
How to enable debug logging
You can enable debug logging for Walrus by setting the environment variable RUST_LOG=walrus=debug. The debug and trace levels provide a more detailed understanding of what a command does or how it fails. This setting complements RUST_LOG=info described above: use RUST_LOG=info when you only need the configuration the client prints at startup (including the path to the Walrus configuration file and the Sui wallet), and RUST_LOG=walrus=debug when you also need the detailed command output.
$ RUST_LOG=walrus=debug walrus store file.txt --epochs 5
If a freshly uploaded blob returns 404 Not Found from a CDN-fronted aggregator, you are likely hitting a cached 404 response from before the blob propagated. See Reading Blobs Right After Upload for when to retry and when not to.
If a deployment fails against a Sui full node that stopped serving JSON-RPC, upgrade the client rather than reconfiguring it. See Migrate from JSON-RPC to gRPC for the upgrade steps covering the CLI, site-builder, and self-hosted full nodes.
Troubleshooting Common Errors
Common errors in the Walrus CLI and network, with causes and solutions.
Error Handling
Best practices for handling Walrus errors.
Migrate from JSON-RPC to gRPC
Upgrade the Walrus CLI and site-builder so they reach Sui over gRPC after the JSON-RPC deprecation, confirm your existing configuration still applies, and recognize the failures that mean you have not migrated yet.
Reading Blobs Right After Upload
Why blobs might return 404 immediately after certification when using a cached aggregator, and how to handle the propagation window.