> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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, artifact validation failures, 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`

The artifacts are not part of the node repository. Copy `genesis.json` and `rollup.json` for your network in from [whitechain-bootstrap](https://github.com/whitechain-labs/whitechain-bootstrap), verifying their SHA-256 against the hashes published there, and place them under `artifacts/<network>/`. The folder name must match the `WHITECHAIN_NETWORK` value in `.env`. See [Network artifacts](/operate/run-a-node/network-artifacts).

```text theme={null}
artifacts/testnet/genesis.json
artifacts/testnet/rollup.json
```

## `L2 chain ID mismatch`, `L2 genesis timestamp mismatch`, or `L1 chain ID mismatch`

`genesis.json` and `rollup.json` in `artifacts/<network>/` do not belong together, or the pair does not belong to the network selected by `WHITECHAIN_NETWORK`. Re-copy both files from the same network directory of [whitechain-bootstrap](https://github.com/whitechain-labs/whitechain-bootstrap) and re-check their SHA-256. See [Artifact validation](/operate/run-a-node/network-artifacts#artifact-validation).

## `jq not found`

`make check-env` uses `jq` to cross-check the artifacts before the node starts. Install it (`apt install jq` or `brew install jq`) and run the target again.

## 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, 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 your own backup 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 backup was taken from the same `WHITECHAIN_NETWORK` and the same profile you start.
3. Make sure the node was stopped during extraction.

See [Back up and restore the datadir](/operate/run-a-node/maintenance#back-up-and-restore-the-datadir) for the full procedure.

## Sync is slow

Common causes, in order of likelihood:

1. A consensus-layer profile (`full-node` or `archive-node`) on a chain with history behind it re-executes every transaction from genesis. Use `full-snap-node` if you need a fast bootstrap.
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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.