> ## Documentation Index
> Fetch the complete documentation index at: https://l2docs.whitechain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common problems and fixes when running a Whitechain RPC node: missing configuration, snapshot issues, slow sync, and transaction errors.

Common issues and their fixes when running a Whitechain RPC node.

## Missing `.env`

No `.env` file found. Copy from `.env.testnet.example` or `.env.mainnet.example` and fill the required values.

```bash theme={null}
cp .env.testnet.example .env
```

See [Node configuration](/operate/run-a-node/configuration) for the full list of variables.

## Missing `artifacts/<network>/genesis.json`

Artifacts are missing or the folder name does not match `WHITECHAIN_NETWORK`. Place `genesis.json` and `rollup.json` under `artifacts/<network>/`. The folder name must match the `WHITECHAIN_NETWORK` value in `.env`.

```
public-rpc-node/artifacts/testnet/genesis.json
public-rpc-node/artifacts/testnet/rollup.json
```

## Compose refuses to start, asks for `PUBLIC_IP`

`PUBLIC_IP` is not set in `.env`. Set it to the public IP the node advertises for P2P.

## Compose refuses to start, asks for `WHITECHAIN_PUBLIC_RPC`

The transaction-forwarding target is not set. Set `WHITECHAIN_PUBLIC_RPC` to the public Whitechain RPC URL in `.env`.

## `WHITECHAIN_RETH_TRUSTED_PEERS` missing (`full-snap-node` only)

The `full-snap-node` profile needs a trusted reth enode to snap-sync from. Set `WHITECHAIN_RETH_TRUSTED_PEERS` to `enode://<pubkey>@<ip>:30303` in `.env`.

## `failed to insert unsafe payload ... node is syncing`

Expected during the initial consensus-layer sync of a fresh `full-node` or `archive-node` database. `op-node` receives an unsafe head over gossip, but `op-reth` has not re-executed up to its parent yet, so the forkchoice update returns `SYNCING`. Meanwhile `Advancing bq origin` log lines show L1 derivation is still progressing. The messages stop once the node catches up. To avoid the long catch-up, restore a snapshot or use `full-snap-node`.

## `full-snap-node` is not snap-syncing

* Confirm `WHITECHAIN_RETH_TRUSTED_PEERS` is a reachable reth enode (`enode://<pubkey>@<ip>:30303`) and the peer is up.
* Confirm outbound EL P2P (devp2p) to that peer is not blocked by a firewall.
* Check that `op-node` logs show `--syncmode=execution-layer` is active and `op-reth` reports syncing against the trusted peer.

## Restored a snapshot but the node resyncs from genesis

Check these three things:

1. Confirm the data landed in the right place: `data/<profile>/op-reth/db` and `data/<profile>/op-reth/static_files` must exist.
2. Confirm the snapshot matches `WHITECHAIN_NETWORK` and the profile you start.
3. Make sure the node was stopped during extraction.

See [Restore from a snapshot](/operate/run-a-node/maintenance#restore-from-a-snapshot) for the full procedure.

## Sync is slow

Common causes, in order of likelihood:

1. No snapshot restored on a long-running `full-node` or `archive-node`, so the node re-executes from genesis. Restore one, or use `full-snap-node`.
2. L1 endpoint is rate-limited or slow. Switch to a faster L1 RPC and Beacon, or run your own L1 node.
3. Disk I/O is the bottleneck. Move `data/` to NVMe storage.

## `optimism_syncStatus` shows `unsafe_l2.number = 0`

The node has not yet inserted the first L2 block. Wait a minute. If it stays at 0:

* Check op-node logs for `Reset of Engine is completed` and `Inserted new L2 unsafe block`. If absent, the engine is not connected. Confirm `op-reth` is healthy on its HTTP port.
* Confirm the genesis block hash in op-node logs matches the one in `rollup.json`.

## `nonce has already been used` when deploying

The node is not fully synced. Wait for the `optimism_syncStatus` lag to drop close to zero before submitting transactions.

```bash theme={null}
echo "behind by $((($(date +%s) - $( \
  curl -s -X POST http://127.0.0.1:9545 \
    -H 'Content-Type: application/json' \
    --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' \
  | jq -r .result.unsafe_l2.timestamp)) / 60)) minutes"
```

## Related

* [Node operators overview](/operate/run-a-node/overview)
* [Run a node](/operate/run-a-node/run-a-node)
* [Node configuration](/operate/run-a-node/configuration)
* [Node maintenance](/operate/run-a-node/maintenance)