Troubleshooting

This guide covers common errors you may encounter when running a Fiber node, along with their causes and solutions.

Payment Errors

Failed to Build Route

Symptom: send_payment returns an error indicating no route could be found.

Possible causes:

• No channel path exists between you and the target node with sufficient liquidity.
• Your local balance is too low in all available channels.
• The target node is not reachable in the network graph.

Solutions:

• Verify your channels have sufficient local balance using list_channels.
• Check that the target node is in the network graph using graph_nodes.
• Open a channel to a well-connected public node to improve reachability.

Payment Timeout

Symptom: A payment stays in Inflight state and never completes.

Possible causes:

• An intermediate node on the route is offline.
• The route has insufficient time locks for the number of hops.

Solutions:

• Wait for the payment to automatically fail and retry.
• Try a different route using build_router and send_payment_with_router.

Channel Errors

Channel Stuck in Awaiting State

Symptom: Channel remains in AwaitingLockin or similar state after opening.

Possible causes:

• The funding transaction has not been confirmed on-chain yet.
• The peer is offline and cannot exchange channel_ready messages.

Solutions:

• Check the funding transaction status on a CKB explorer.
• Ensure the peer is connected using list_peers.

Cannot Open Channel

Symptom: open_channel fails immediately.

Possible causes:

• You are not connected to the target peer.
• Insufficient CKB balance for the funding amount plus channel reserve (99 CKB per side).
• The peer has rejected the channel opening request.

Solutions:

• Connect to the peer first using connect_peer.
• Verify your CKB balance is sufficient.
• Check the peer's auto_accept configuration.

Connection Errors

HTTP 503 / RPC Unavailable

Symptom: RPC calls return HTTP 503 or connection refused.

Possible causes:

• The node is not running.
• The RPC port is not accessible (firewall, wrong address).
• Biscuit authentication is required but not provided.

Solutions:

• Verify the node process is running.
• Check config.yml for the correct RPC listen address.
• Provide a valid Biscuit auth token if RPC is protected.

macOS Gatekeeper Blocks fnn Binary

Symptom: macOS prevents the fnn binary from running with a security warning.

Solution:

1. Go to System Settings > Privacy & Security.
2. Click Open Anyway next to the security warning.
3. Alternatively, run: xattr -d com.apple.quarantine /path/to/fnn

Configuration Issues

Wrong Secret Key Password

Symptom: Node fails to start with Secret key file error: decryption failed.

Solution:

• Ensure the FIBER_SECRET_KEY_PASSWORD environment variable matches the password used when the key was encrypted.
• If you have lost the password but have a plaintext private key, refer to the Backup Guide for recovery steps.

Peer ID vs Pubkey (v0.8.0+ Migration)

Symptom: RPC calls using peer_id parameter fail.

Cause: Since v0.8.0, Fiber uses pubkey (hex-encoded secp256k1) instead of peer_id (base58) for peer identification.

Solution:

• Update all RPC calls to use pubkey instead of peer_id.
• Refer to the v0.8.0 migration guide for a complete list of changes.