Resolve common issues with the Walrus CLI, configuration, and network connectivity.

## Use the latest binary

Before undertaking any other steps, make sure you have the [latest `walrus` binary](/docs/getting-started/advanced-setup). If you have multiple versions in different locations, find the binary that is actually used with `which walrus`.

## 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](/docs/getting-started/advanced-setup) the `ubuntu-x86_64-generic` version instead, which is compiled to be compatible with almost all physical and virtual x86-64 CPUs.

## Verify correct 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](/docs/getting-started).

## Update to 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](/docs/getting-started) and make sure the CLI uses the intended configuration.

> **Tip**
>
> 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.
## 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.
```
$ 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](/docs/troubleshooting/reading-blobs-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](/docs/troubleshooting/grpc-migration) for the upgrade steps covering the CLI, `site-builder`, and self-hosted full nodes.

- [Error Handling](/docs/troubleshooting/error-handling): Best practices for handling Walrus errors.
- [Migrate from JSON-RPC to gRPC](/docs/troubleshooting/grpc-migration): 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.
- [Troubleshooting Common Errors](/docs/troubleshooting/network-errors): Common errors in the Walrus CLI and network, with causes and solutions.
- [Reading Blobs Right After Upload](/docs/troubleshooting/reading-blobs-after-upload): Why blobs might return 404 immediately after certification when using a cached aggregator, and how to handle the propagation window.