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.

Fee Too High

Symptom: send_payment fails with status Failed and a fee-related error.

Possible causes:

• The cumulative relay fees along the route exceed your max_fee_amount or max_fee_rate budget.
• The route is longer than expected, accumulating more fees per hop.

Solutions:

• Increase max_fee_amount or max_fee_rate in your send_payment call.
• Use dry_run: true to preview the route and estimated fees before committing funds.
• Try a shorter route by specifying explicit hops with build_router.

See Payment Lifecycle for details on how the fee budget works.

Partial Payment Delivered

Symptom: A multi-path payment (MPP) shows Inflight with no progress — some parts have succeeded while others are stuck or failed.

Possible causes:

• Some routes have sufficient liquidity while others do not.
• One or more attempts failed with retryable errors, and the retry limit has been reached.

Solutions:

• Check last_error on the payment to identify which attempt failed.
• Wait for the system's automatic retry mechanism to find alternate paths.
• If the payment times out, retry with a higher max_parts value to increase route diversity.

Invoice Amount Mismatch

Symptom: send_payment fails with IncorrectOrUnknownPaymentDetails or Failed.

Possible causes:

• The invoice amount does not match what the sender expected to pay.
• The invoice has expired (current time exceeds timestamp + expiry).
• The payment hash does not correspond to any known invoice on the recipient's node.

Solutions:

• Verify the invoice amount and expiry using parse_invoice before paying.
• If the invoice has expired, request a new one from the recipient with a longer expiry.
• Confirm the payment hash matches the invoice you intend to pay.

Payment Error Codes Reference

When a payment fails, the failed_error field contains a decoded error code from the failing hop. The most common codes are:

See Multi-Hop Payments for a full explanation of error handling and retry behavior.

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.

One-Way Channel Cannot Be Public

Symptom: open_channel with both one_way: true and public: true fails with "An one-way channel cannot be public".

Cause: Unidirectional channels are always private. The node enforces this restriction because one-way channels cannot route third-party payments, so advertising them in the network graph would be misleading.

Solution:

• Remove the public: true flag. One-way channels must be private.
• If you need a public channel that can route payments in both directions, use a standard bidirectional channel instead.

Reverse Payment Fails on One-Way Channel

Symptom: send_payment from the acceptor back to the initiator on a one-way channel fails with Failed to build route.

Cause: In a unidirectional channel, funds can only flow from initiator to acceptor. The routing engine cannot find a valid path for a reverse-direction payment.

Solutions:

• Open a separate channel in the reverse direction if the acceptor needs to pay the initiator.
• Use a bidirectional channel if you expect payments to flow in both directions.

See Unidirectional Channel for the full specification and use-case trade-offs.

Invoice Errors

Settling Too Early

Symptom: settle_invoice returns InvoiceStillOpen.

Cause: The invoice is still in the Open state — no incoming TLC has arrived yet. You can only settle a hold invoice once a payment has reached your node and the invoice transitions to Received.

Solutions:

• Wait for the sender's payment to propagate through the network and reach your node.
• Verify the sender has actually called send_payment and check the payment status on their side.
• Use get_invoice to monitor the invoice status; settle once it shows Received.

Settling After Expiry

Symptom: settle_invoice returns InvoiceAlreadyExpired.

Cause: The invoice's expiry time (timestamp + expiry) has passed. Expired invoices cannot be settled even if the preimage is valid.

Solutions:

• Create a new invoice with a longer expiry value and have the sender pay again.
• When creating hold invoices for time-sensitive operations (e.g., atomic swaps), set a generous expiry to account for network propagation delays.

Wrong Preimage

Symptom: settle_invoice returns HashMismatch.

Cause: The preimage you provided does not hash to the invoice's payment_hash. This typically happens when the preimage was generated separately and the wrong one was used, or when it was corrupted during storage.

Solutions:

• Double-check that you are using the exact preimage that was used to compute the payment_hash.
• If generating preimages programmatically, verify the hash immediately after creation: sha256(preimage) == payment_hash.

Preimage Lost Before Settlement

Symptom: A hold invoice is in Received state but you cannot settle it because the preimage is lost.

Cause: The preimage was not stored securely after the invoice was created, and is no longer recoverable.

Solution:

• Wait for the invoice to expire. Once the expiry time passes, the held TLCs are automatically released and funds return to the sender.
• To prevent this in the future, always store the preimage in a secure location before creating the invoice.

See Hold Invoice for the complete hold invoice lifecycle and trust model.

Cannot Cancel Invoice

Symptom: cancel_invoice fails or is rejected.

Cause: The invoice is already in the Paid or Cancelled state. Only invoices in Open, Received, or Expired state can be cancelled.

Solution:

• Check the current invoice status with get_invoice. If it is Paid, the payment has already been settled and cannot be reversed. If it is Cancelled, no further action is needed.

Trampoline Routing Errors

Trampoline Feature Not Supported

Symptom: A trampoline payment fails with RequiredNodeFeatureMissing.

Cause: The trampoline node specified in trampoline_hops does not support trampoline routing (feature bit 5, TRAMPOLINE_ROUTING is not enabled).

Solutions:

• Use a different trampoline node that advertises trampoline routing support.
• Check the node's features using graph_nodes or contact the node operator.
• By default, Fiber nodes advertise trampoline routing as a required feature — if the node is running an older version, it may not support it.

Trampoline Sub-Route Fee Insufficient

Symptom: A trampoline payment fails with FeeInsufficient originating from a trampoline node.

Cause: The build_max_fee_amount allocated to the trampoline hop is too small to cover the relay fees on the sub-route between two trampoline nodes. This often happens when the sender underestimates the fee budget or when relay fees on the sub-route are higher than expected.

Solutions:

• Retry with a higher max_fee_amount to give trampoline nodes a larger fee budget.
• Try different trampoline hops that may have shorter or cheaper sub-routes.
• Use dry_run: true to estimate the total fee before sending.

See Trampoline Routing for a detailed explanation of the two-level fee structure and error handling.

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.

Related Topics

• Payment Lifecycle — payment states, attempts, and the TLC state machine
• Invoice — creating, paying, and managing invoices
• Hold Invoice — deferred settlement and common hold invoice issues
• Multi-Hop Payments — routing, error handling, and retry behavior
• Trampoline Routing — delegated pathfinding for lightweight clients
• Unidirectional Channel — one-way channel constraints and limitations