Troubleshooting Walrus Sites

To fix a common Walrus Sites error, match the error message to its entry, then apply the solution. These errors occur in 3 places: site-builder configuration, site-builder deploy, and browsing a site through a portal. Each entry names the error, its cause, and a solution.

Commands use uppercase placeholders, such as EPOCHS, DIRECTORY, OBJECT_ID, and SITE_OBJECT_ID. Replace each placeholder with your own value before you run the command.

How to fix configuration errors

Errors in this section relate to site-builder configuration.

site-builder: command not found

Cause: The site-builder binary is not in a directory that your shell searches when running commands.

Solution: Move the binary to a directory included in your $PATH (the list of directories your shell searches for commands), or add its current location:

$ export PATH=$PATH:/path/to/site-builder-directory

Confirm the installation succeeded:

$ site-builder --version

No such file or directory: sites-config.yaml

Cause: The site-builder cannot find its configuration file. By default, it searches the current directory, $XDG_CONFIG_HOME/walrus/sites-config.yaml, and $HOME/.config/walrus/sites-config.yaml, in that order.

Solution: Download a fresh copy of the configuration file for your target network:

$ curl https://raw.githubusercontent.com/MystenLabs/walrus-sites/refs/heads/mainnet/sites-config.yaml \
  -o ~/.config/walrus/sites-config.yaml

If you store the file in a non-default location, pass its path explicitly:

$ site-builder --config /path/to/sites-config.yaml deploy --epochs EPOCHS DIRECTORY

the specified Walrus system object does not exist

Cause: The site-builder points to a Walrus system object that does not exist on the current network. This happens when you use an outdated sites-config.yaml or when Testnet has been wiped.

Solution: Download the latest sites-config.yaml for your target network (see the solution above). Verify that the wallet_env and walrus_context fields in sites-config.yaml match the network you intend to deploy to.

---

How to fix deployment errors

Errors in this section occur when running site-builder deploy.

could not retrieve enough confirmations to certify the blob

Cause: The site-builder cannot gather enough confirmations from Walrus storage nodes to certify the uploaded blob. This typically indicates that your configuration points to an inactive or outdated Walrus system, or that Testnet is temporarily unavailable.

Solution: Download the latest configuration file for your target network and retry. If the problem persists on Testnet, check the Walrus Discord for announcements about network availability.

InsufficientCoinBalance or GasBudgetTooLow

Cause: Your wallet does not have enough SUI to cover the transaction gas fee, does not have enough WAL to pay for Walrus storage, or the site is big and the default gas_budget isn't enough (0.5 SUI).

Solution: Increase the gas_budget in the sites-config or pass --gas-budget.

Check your wallet balance:

$ sui client balance

On Testnet, get SUI from the faucet and exchange it for WAL:

$ walrus get-wal

On Mainnet, acquire WAL through an exchange or transfer before deploying.

Error: The wallet must own the site object to update it

Cause: You are trying to update a Walrus Site using a wallet that does not own the site's Sui object. Only the wallet that owns the site object can run deploy in update mode.

Solution: Verify ownership by looking up the site's object ID in a Sui network explorer. If you need to move ownership to a different wallet, transfer the site object:

$ sui client transfer --object-id SITE_OBJECT_ID --to NEW_WALLET_ADDRESS --gas-budget 10000000

Why does deploy publish a new site instead of updating?

Cause: The deploy command creates a new site object when it cannot find an existing object ID. It checks the --object-id flag first, then the object_id field in ws-resources.json. If neither is present, a new site is created.

Solution: Pass the object ID of your existing site directly. Replace OBJECT_ID with the object ID from the output of the site-builder deploy that first published your site:

$ site-builder deploy --object-id OBJECT_ID --epochs EPOCHS DIRECTORY

After the first deploy, site-builder writes the object ID to ws-resources.json automatically. For subsequent deploys, verify this file is present in your site root and contains the correct object_id value.

---

How to fix browsing errors

Errors in this section occur when accessing a site through a portal.

Why does a site not load on wal.app?

Cause: The wal.app portal only serves Mainnet sites. If your site is deployed to Testnet, the portal cannot resolve it. The wal.app portal also requires a SuiNS name and does not support Base36 object ID subdomains.

Solution: If your site is on Testnet, run a local portal to access it. If your site is on Mainnet but has no SuiNS name, assign one through the SuiNS app and link it to your site's object ID.

Why does a SuiNS name not resolve to the correct site?

Cause: Your SuiNS name points to a different object ID than your current site, or the record has not propagated yet.

Solution: Open the SuiNS app, navigate to your name's settings, and verify the linked object ID matches the output from your most recent site-builder deploy. Allow a few minutes for changes to propagate, then hard-refresh your browser (Ctrl+Shift+R or Cmd+Shift+R).

Why do pages return a 404 error on direct URL access?

Cause: The portal fetches the requested URL path as a file from Walrus. For single-page applications that use client-side routing, those paths do not correspond to real files, so the request returns a 404 error.

Solution: Add a catch-all routing rule to ws-resources.json that maps unmatched paths to index.html, then redeploy:

{
  "routes": {
    "/*": "/index.html"
  }
}

caution

Walrus Sites does not support server-side redirects. Redirect plugins used by frameworks like Docusaurus resolve routes at the server level, which is not available on Walrus Sites. Use the routes field in ws-resources.json for client-side routing instead.

Why do routes return HTTP 503 with Content-Security-Policy headers?

Cause: Restrictive Content-Security-Policy headers in ws-resources.json (specifically default-src 'none' and frame-ancestors 'none') conflict with the Walrus portal's request processing pipeline. Direct resource requests (for example, /index.html) bypass route resolution and return 200, but route redirects (for example, / to /index.html) fail with a 503 error.

Solution: Remove restrictive CSP and security headers from ws-resources.json:

• Content-Security-Policy
• X-Frame-Options: DENY
• Permissions-Policy
• Referrer-Policy
• X-Content-Type-Options

These headers are appropriate for self-hosted sites but conflict with the Walrus portal's route resolution.