Troubleshooting

If your status looks wrong or a claim fails, start here.

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 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 [email protected]. 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).