Solutions to common errors when deploying and browsing 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](https://discord.gg/walrusprotocol) 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](https://suins.io/) 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](https://suins.io/), 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:

```json
{
  "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.