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

# Troubleshooting

### My status is stuck on "qualifying"

Brand-new nodes typically clear qualifying in 1–2 review periods (10–20 minutes). If you're stuck longer:

1. Confirm the gateway can reach you. Open a terminal and check the log for `health probe ok` lines. If you only see `health probe failed`, the gateway can't connect.
2. Test your network mode: UPnP can silently fail on some routers. Try **Manual** with explicit port forwarding, or **Tunnel** via bore/ngrok.
3. Confirm your stake landed on chain. Open the staking dApp and check that your staked balance is at or above the minimum.

### My status flips between "qualifying" and "inactive"

You have intermittent connectivity. Common causes:

* UPnP lease expired and didn't renew (some consumer routers).
* ISP routes you through CGNAT — UPnP can't help. Switch to a tunnel.
* Your machine sleeps overnight. Disable sleep on the host.

### My status says "unstaked" but I staked

Check that the staking address shown in the app matches the wallet that holds the stake. The two must be the same. If they don't match, click **Reset Node** (back up your identity key first) and re-run setup with the right address.

### The status badge says "inactive" right after I clicked Start

Look at the log:

```
tail -f ~/.spacerouter/logs/spacerouter-node.log
```

Common log lines:

| Log line                       | Meaning                             | Fix                                                                               |
| ------------------------------ | ----------------------------------- | --------------------------------------------------------------------------------- |
| `port 9090 in use`             | Another process is already on 9090. | Pass `--port 9091` or stop the other process.                                     |
| `upnp failed`                  | Router doesn't support UPnP.        | Switch to Manual or Tunnel mode.                                                  |
| `identity-key decrypt failed`  | Wrong passphrase.                   | Re-enter, or set `SR_IDENTITY_PASSPHRASE`.                                        |
| `coordination api unreachable` | Outbound HTTPS blocked.             | Check firewall — the node makes outbound HTTPS to `coordination.spacerouter.org`. |

### Claim failed with "insufficient funds"

Your **Identity** wallet — not your staking wallet — pays gas for claims, and it's out of CTC. Find the address on the Earnings screen and send **\~1 CTC** to it. Detailed explanation: Before your first claim.

### Claim failed with "CLAIM\_REVERTED"

A revert almost always means the receipt was already settled in a previous batch (the contract refuses to double-claim). Check Blockscout — if the SPACE arrived in your collection wallet, no action is needed. The Earnings screen will show the receipt as **claimed** after the next reaper tick.

### "failed\_terminal" receipts I can't recover

Once a receipt is locked, the SPACE on it is unrecoverable from your side. The good news: each terminal failure shows you the reason, so you can prevent the next one:

* `SIGN_REJECTED_CLOCK_SKEW` → Enable NTP / time sync on the host.
* `SIGN_REJECTED_BAD_SIGNATURE` → Identity key file may be corrupt; restore from backup.
* `SIGN_REJECTED_UNREGISTERED_NODE` →Your wallet wasn't yet registered with the network when this receipt was created. Registration runs on the staking-approval review cycle (every 4 hours); future receipts will succeed once you're approved.

### I'm behind CGNAT — how do I tunnel?

Two common options:

#### bore (free, requires no signup)

```
# Install bore (Rust)
cargo install bore-cli

# Run it pointing to your local node port
bore local 9090 --to bore.pub

# bore prints:
# listening at bore.pub:46213
# Use that hostname/port in SpaceRouter Tunnel mode.
```

#### ngrok (paid for stable hostnames)

```
ngrok tcp 9090
# Forwarding tcp://0.tcp.ngrok.io:12345 -> localhost:9090
# Use the printed host:port in SpaceRouter Tunnel mode.
```

Either way, set Network mode to **Tunnel** and paste the hostname + port from the tunnel.

### The app crashes or won't open

1. Quit any running instance.
2. Move the data directory out of the way (don't delete): `mv ~/.spacerouter ~/.spacerouter.bak`.
3. Re-launch — you'll get a fresh setup screen.
4. If the app now starts, the issue is config-related. Restore the identity key from the backup: `cp ~/.spacerouter.bak/certs/node-identity.key ~/.spacerouter/certs/`.
5. If it still crashes, file a bug at [github.com/space-labs/space-router-node/issues](https://github.com/space-labs/space-router-node/issues) with the last 100 log lines.

### My identity key was lost / machine died

If you don't have a backup, you can't restore the same node identity. You'll need to:

1. Install fresh on the new machine.
2. Generate a new identity (or import any backup you might have).
3. Use the same staking address you were using before — your stake stays where it is.
4. Your status will start at **qualifying** again until the next review period approves the new identity.

Any unclaimed earnings tied to the old identity are unrecoverable. Going forward, back up `node-identity.key` the moment you set it up.

### Still stuck?

Email <router.support@spacenetwork.com>. Include:

* Your node identity address (in the Wallet panel).
* Your status state and how long you've been there.
* The last 100 log lines, with private keys redacted.
* Your OS and SpaceRouter version (`--version`).