> For the complete documentation index, see [llms.txt](https://docs.lumia.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lumia.org/run-a-node/node-troubleshooting.md).

# Node troubleshooting

**Who this is for:** operators whose Lumia node isn't syncing, isn't reachable, or is behaving unexpectedly after deployment. By the end you should be able to match your symptom to a cause and a fix, or know where to escalate if you can't.

**You should already know:** the deployment steps in [Run a local validium node](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/run-a-node/zknode/run-a-local-validium-node).

**Treat exact paths, ports, and version numbers below as illustrative, and confirm against your own deployment's actual configuration.**

### Sync issues

<details>

<summary>Data-directory corruption errors during or after a snapshot extract</summary>

Cause: ran out of disk mid-extract.

{% hint style="warning" %}
Deleting the data directory discards everything the node has already synced, and there is no undo. Check the path you are about to remove, and confirm that any keys or config stored under it are backed up first.
{% endhint %}

Fix: free space, delete the data directory, and re-extract from a fresh download. Don't try to resume a corrupted extract.

</details>

<details>

<summary>Sync stalls with repeated L1 errors in the logs</summary>

Cause: your L1 RPC endpoint is rate-limited (common with free-tier providers). Fix: switch to a paid/premium L1 provider; if the plan is still tight during initial catch-up, consider raising your client's L1 query delay / lowering its L1 block-range setting.

</details>

<details>

<summary>A burst of L1 429 (rate-limit) errors specifically during initial catch-up, dropping off afterward</summary>

Cause: expected. The execution client scans L1 in parallel during catch-up and retries throttled calls, which itself counts against the quota. Fix: not a fault by itself; confirm sync still completes. If the volume is a problem for your provider relationship, see the L1 RPC fix above.

</details>

<details>

<summary>Local block number appears frozen even though the node is clearly still working (CPU/disk active, logs advancing)</summary>

Cause: some execution clients only advance the reported head once specific internal sync stages complete. The number can lag behind real progress. Fix: check the logs for stage-progress messages rather than trusting `eth_blockNumber` alone during catch-up.

</details>

<details>

<summary>Node was offline for an extended period and is now very far behind</summary>

Cause: a long offline gap can trigger an expensive internal state rebuild on resume. Fix: let it run, or re-bootstrap from a current snapshot instead of waiting out a rebuild from an old state.

</details>

<details>

<summary>Wrong chain ID returned by <code>eth_chainId</code></summary>

Cause: wrong network configuration, or a stale environment file left over from a previous setup.

{% hint style="warning" %}
Wiping the data directory destroys the node's synced state permanently. Confirm the configuration is genuinely wrong for the network you intend to run before you do it, so you don't throw away a good sync over a typo, and back up anything stored under that directory.
{% endhint %}

Fix: re-check your network configuration against [/reference/networks](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/reference/networks-and-endpoints), wipe the data directory, and redeploy clean.

</details>

### Connectivity issues

<details>

<summary>RPC/WS ports reachable from the public internet even though your host firewall denies inbound</summary>

Cause: container runtimes commonly insert their own network rules ahead of a host firewall like UFW, so a container port publish bypasses it. Fix: bind published ports to localhost explicitly and put a reverse proxy in front for anything you actually intend to expose. See [JSON-RPC endpoints](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/run-a-node/rpc-node/json-rpc-endpoints).

</details>

<details>

<summary>WebSocket connections reset immediately</summary>

Cause: the client's WS listener can default to binding only the container/process loopback address, which a port mapping can't reach. Fix: explicitly bind the WS listener to a reachable interface in your node's config.

</details>

<details>

<summary>Metrics endpoint returns 404 at the path you expected</summary>

Cause: some execution clients serve Prometheus metrics on a non-default path rather than the conventional `/metrics`. Fix: check your specific client's documented metrics path rather than assuming the generic default.

</details>

### Where to get help

If none of the above matches your symptom, don't guess at a fix that touches your data directory or keys. Reach out via [`/support/contact`](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/support-and-community/contact-and-support-channels).