# Validator Troubleshooting

## `fee not provided` or `insufficient fee`

Symptom:

- `create-validator` returns `fee not provided`
- raw log mentions insufficient fee

Fix:

```bash
cd /opt/axon-node
KEYRING_PASSWORD_FILE=/opt/axon-node/keyring.pass \
COMETBFT_RPC=http://127.0.0.1:26657 \
GAS_PRICES=1000000000aaxon \
./start_validator_node.sh create-validator
```

Use a non-zero gas price until the local helper script already defaults to one.

The same non-zero gas policy applies to:

- `axond tx agent register`
- `axond tx agent heartbeat`

## `catching_up` stays `true`

Checks:

```bash
curl -s http://127.0.0.1:26657/status | jq '.result.sync_info'
cat /opt/axon-node/data/peer_info.txt
tail -f /opt/axon-node/data/node.log
```

Actions:

- confirm the bootstrap peers file matches the official repository
- confirm the node has reachable peers
- confirm disk and network are not constrained
- wait before any validator transaction

Do not submit `create-validator` until `catching_up=false`.

## `heartbeat sent too frequently`

Symptom:

- `axond tx agent heartbeat` is rejected with `heartbeat sent too frequently`

Cause:

- the current chain heartbeat interval is `100` blocks
- sending a heartbeat too soon will fail

Fix:

- wait until at least `100` new blocks pass after the previous heartbeat
- query the Agent record to compare `last_heartbeat` with the current block height

Checks:

```bash
curl -s http://127.0.0.1:26657/status | jq '.result.sync_info.latest_block_height'
axond query agent agent "$(cat /opt/axon-node/data/validator.address)" \
  --node http://127.0.0.1:26657 \
  --output json
```

## Missing `KEYRING_PASSWORD_FILE`

Symptoms:

- the script refuses to run
- the keyring password file is missing or empty

Fix:

```bash
ls -l /opt/axon-node/keyring.pass
cat /opt/axon-node/keyring.pass
chmod 0600 /opt/axon-node/keyring.pass
```

Use a non-empty local passphrase file and point `KEYRING_PASSWORD_FILE` at it.

## Validator not found after submission

Checks:

```bash
curl -s http://127.0.0.1:1317/cosmos/tx/v1beta1/txs/<TX_HASH>
axond query staking validator "$(cat /opt/axon-node/data/validator.valoper)" \
  --node http://127.0.0.1:26657 \
  --output json
```

Possible causes:

- the transaction never landed
- the validator transaction was rejected
- the wrong RPC endpoint was queried

If the user is running Docker with remapped ports, replace the default `26657` and `1317` values with the actual host ports, for example `27657` and `11317`.

## Agent not found after registration attempt

Checks:

```bash
axond query tx <TX_HASH> \
  --node http://127.0.0.1:26657 \
  --output json

axond query agent agent "$(cat /opt/axon-node/data/validator.address)" \
  --node http://127.0.0.1:26657 \
  --output json
```

Common causes:

- the account was already short on liquid balance after `create-validator`
- the wrong key or home directory was used
- the validator account and the Agent account were not the same address
- the transaction succeeded on a different RPC endpoint than the one being queried

## No peers or unstable peers

Checks:

```bash
tail -f /opt/axon-node/data/node.log
cat /opt/axon-node/bootstrap_peers.txt
```

Actions:

- re-sync the official bootstrap peers file
- verify outbound connectivity to `mainnet-node.axonchain.ai:26656`
- only set `P2P_EXTERNAL_ADDRESS` when the host is publicly reachable

## Chain ID confusion

- `axon_8210-1` is the Cosmos chain ID for validator and node commands
- `8210` is the EVM chain ID for wallets

If the user mixes them, correct the command before continuing.