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

# Troubleshooting

> Common issues running a Quantum Chain node and how to fix them.

## Node won't start

<AccordionGroup>
  <Accordion title="Fatal: database contains incompatible genesis (have X, new Y)">
    The data directory was previously initialized with a different genesis file.

    **Fix:** either pick a fresh `--datadir`, or wipe the existing one:

    ```bash theme={null}
    rm -rf /var/lib/geth/geth/chaindata
    geth --datadir /var/lib/geth init genesis.json
    ```
  </Accordion>

  <Accordion title="bind: address already in use">
    Another process is using the port (`30303`, `8545`, or `8546`).

    **Fix:** find it with `lsof -i :8545` and stop it, or pick a different port via `--port`, `--http.port`, `--ws.port`.
  </Accordion>

  <Accordion title="too many open files">
    Linux's default `ulimit -n` is too low for a full node.

    **Fix:** raise it. In systemd: `LimitNOFILE=65536`. In a shell: `ulimit -n 65536`.
  </Accordion>
</AccordionGroup>

## Sync issues

<AccordionGroup>
  <Accordion title="Sync stalls or peer count is 0">
    Quantum Chain mainnet uses dedicated bootnodes. If your node is firewalled, discovery cannot work.

    **Fix:** open inbound UDP+TCP `30303`, or pass `--bootnodes <enode>` for a known peer.
  </Accordion>

  <Accordion title="Sync is much slower than expected">
    Snap sync needs sustained disk write bandwidth. HDDs and slow SSDs throttle the chain.

    **Fix:** use NVMe storage. For full and archive nodes, allocate `--cache 4096` or higher.
  </Accordion>

  <Accordion title="Errors importing block: invalid quantum signature">
    Your node is running an old binary that pre-dates `quantumVerificationBlock`.

    **Fix:** rebuild from a tagged release: `git fetch --tags && git checkout <tag> && make geth`.
  </Accordion>
</AccordionGroup>

## Validator (Clique) issues

<AccordionGroup>
  <Accordion title="My sealer is not producing blocks">
    Possible causes:

    * The address isn't in the sealer set. Check with `clique.getSigners()`.
    * The account is locked. Pass `--unlock` and `--password`.
    * The node hasn't synced. Sealers must be at the head before they can seal.
    * It is "out of turn" — wait until the in-turn slot.
  </Accordion>

  <Accordion title="recently signed warning">
    A sealer must wait `(N/2 + 1)` blocks between blocks it signs. This is anti-malleability protection in Clique. The warning resolves itself.
  </Accordion>

  <Accordion title="Proposed sealer change isn't taking effect">
    Sealer changes are applied at the next epoch boundary (every 30 000 blocks on mainnet). Use `clique.proposals` to confirm your vote is recorded.
  </Accordion>
</AccordionGroup>

## RPC issues

<AccordionGroup>
  <Accordion title="403 Forbidden / unauthorized origin">
    `--http.corsdomain` and `--http.vhosts` block the request.

    **Fix:** add your origin (`--http.corsdomain "https://app.example.com"`) and host (`--http.vhosts "rpc.example.com"`).
  </Accordion>

  <Accordion title="method not found">
    The RPC namespace is not enabled.

    **Fix:** include it in `--http.api`. For example, `eth,net,web3,debug,trace`.
  </Accordion>

  <Accordion title="gas required exceeds allowance">
    Default `--rpc.gascap` is 50 000 000. Heavy `eth_call` queries can hit it.

    **Fix:** raise the cap, or split the call.
  </Accordion>
</AccordionGroup>

## Transaction issues

<AccordionGroup>
  <Accordion title="nonce too low">
    A transaction with this nonce was already mined or replaced.

    **Fix:** fetch the next nonce with `eth_getTransactionCount(addr, "pending")`.
  </Accordion>

  <Accordion title="replacement transaction underpriced">
    To replace a pending transaction, the new one must have a fee at least 10% higher.

    **Fix:** raise the gas price (legacy) or `maxFeePerGas` (EIP-1559) by 10%+.
  </Accordion>

  <Accordion title="transaction stuck in mempool">
    Either the gas price is below the network minimum or the nonce has a gap.

    **Fix:** check `txpool_status`. For nonce gaps, fill the missing nonce. For low fees, replace at a higher fee.
  </Accordion>

  <Accordion title="invalid sender / signature verification failed">
    The post-quantum signature does not verify against the public key registered for the sender address.

    **Fix:** confirm the signing service is using the correct key for the wallet, and that you targeted `chainId=20803`.
  </Accordion>
</AccordionGroup>

## Disk usage

```bash theme={null}
du -sh /var/lib/geth/geth/chaindata
```

If the database is growing faster than expected on a full node, prune:

```bash theme={null}
systemctl stop geth
geth snapshot prune-state --datadir /var/lib/geth
systemctl start geth
```

Archive nodes cannot be pruned — that's the design tradeoff.

## Where to look

| Source                            | What it tells you  |
| --------------------------------- | ------------------ |
| `journalctl -u geth -f`           | Live logs          |
| `eth_syncing`                     | Sync progress      |
| `txpool_status`, `txpool_content` | Mempool contents   |
| `clique_status`                   | Sealer health      |
| `:6060/metrics`                   | Prometheus metrics |
| `admin_peers`                     | Connected peers    |

## Where to go next

* [Running a node](/quantum-chain/running-a-node)
* [Networks and validators](/quantum-chain/networks)
* [Qustody troubleshooting](/qustody/troubleshooting)