Troubleshooting Walrus Sites

This page covers common errors when deploying and browsing Walrus Sites, organized by where they occur.

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, 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.

---

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

Deploy publishes 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:

$ 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.

---

Browsing errors

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

Site does 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.

SuiNS name does 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).

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.

HTTP 503 on route resolution 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.