Lightning Network Error Code Reference

Lightning Network Error Codes

Lightning Network error codes are defined across multiple BOLT specifications and serve two distinct purposes: signaling payment routing failures back to the sender (BOLT #4 onion failure codes) and communicating peer-to-peer channel errors between directly connected nodes (BOLT #1 error and warning messages). Understanding these codes is essential for debugging failed payments, diagnosing channel issues, and building reliable Lightning applications.

This reference covers every failure code in the current specification, explains the bit-flag system used to classify failures, maps common developer-facing errors to their BOLT-level codes, and provides troubleshooting guidance for each.

How Failure Codes Are Structured

BOLT #4 failure codes are 16-bit integers. The top four bits are flags that classify the error, while the lower 12 bits identify the specific failure. The final code is constructed by OR-ing the flags with the base error number. For example, unknown_next_peer has base number 10 and the PERM flag (0x4000), producing a final code of 0x400A (16394 decimal).

These flags tell the sender how to react. A PERM failure means the sender should not retry on the same route. An UPDATE failure indicates that the sender's routing graph is stale and should be refreshed. A NODE failure means the entire node should be avoided, not just the specific channel. BADONION failures indicate corrupted onion routing packets.

BOLT #4 Onion Failure Codes

These failure codes travel inside encrypted return packets via update_fail_htlc (message type 131) and are decrypted by the payment sender. They are the primary error codes you encounter when a Lightning payment fails mid-route. Each code includes data fields that help the sender diagnose the issue.

Note: Three legacy codes have been deprecated. invalid_realm (0x4001) was removed in 2024 when the realm byte was dropped from the onion format. incorrect_payment_amount (0x4010) and final_expiry_too_soon (0x0011) were merged into incorrect_or_unknown_payment_details to prevent payment probing attacks.

Peer-to-Peer Error Messages (BOLT #1)

Separate from onion failure codes, BOLT #1 defines error (type 17) and warning (type 1) messages for direct peer-to-peer communication. These are not payment-path failures: they signal channel-level problems between two directly connected nodes.

An error message is fatal: the receiving node MUST fail the referenced channel (or all channels with the peer if the channel_id is all zeros). This triggers a unilateral force close. A warning message is non-fatal: it should be logged and may prompt a graceful shutdown negotiation but does not require immediate channel closure.

Common triggers for peer-to-peer error messages include:

• Invalid or non-standard signatures on commitment transactions
• Channel reserve requirement violations
• Funding transaction not confirmed within the expected window
• Protocol version or feature negotiation failures
• HTLC limit or dust threshold violations
• Unrecoverable internal errors at either node

Common Developer Errors and Their Codes

The error messages surfaced by Lightning node implementations (LND, CLN, Eclair, LDK) often use human-readable strings rather than raw BOLT codes. The following table maps common developer-facing errors to their underlying BOLT failure codes.

Troubleshooting Payment Failures

When a payment fails, the encrypted failure message travels back through each hop of the onion route until it reaches the sender. The sender decrypts the failure to determine which node returned the error and why. Use the Lightning invoice decoder to inspect invoice parameters and verify that payment details are correct before debugging routing issues.

Temporary vs. Permanent Failures

If a failure code lacks the PERM flag (bit 14), the issue may resolve on its own. For temporary_channel_failure (0x1007), the most common Lightning error, the channel may regain capacity after pending HTLCs settle. Retry after a brief delay or let your node's pathfinder select an alternate route. For PERM failures like unknown_next_peer (0x400A), the sender should immediately remove the failing channel from its routing graph and not retry on the same path.

UPDATE Failures and Stale Routing Data

Failure codes with the UPDATE flag (bit 12) indicate that the sender's routing graph contains outdated channel parameters. The failure message may include a channel_update with the current fee rate, CLTV delta, or minimum HTLC size. Your node should apply this update before recalculating a route. If you see frequent UPDATE failures, your node may not be receiving gossip messages efficiently: check peer connectivity and gossip sync status.

BADONION Failures

BADONION failures (bit 15) mean the onion packet itself was corrupted or malformed. These are always permanent. They can indicate a bug in the sender's onion construction, network-level packet corruption, or a malicious intermediate node stripping or modifying the onion. Since the onion cannot be parsed, the failing node sends the error via update_fail_malformed_htlc (message type 135) instead of the standard encrypted failure path.

Blinded Path Errors

Blinded paths, introduced for receiver privacy in BOLT 12, use the catch-all code invalid_onion_blinding (0xC018) for any error within the blinded segment. This deliberately hides the actual failure reason to prevent the sender from learning which hop within the blinded path failed. If you encounter this error, retry with the same or an alternate blinded path: you cannot diagnose the specific issue from the sender's perspective.

Error Handling Architecture

The Lightning Network uses two distinct error systems that operate at different layers of the protocol stack:

• BOLT #4 onion failure codes are encrypted and travel backward through the payment path inside update_fail_htlc messages. Only the original sender can decrypt and read them. Intermediate nodes cannot see failure codes from downstream hops
• BOLT #1 error/warning messages are plaintext and exchanged directly between two connected peers. They affect the channel between those peers specifically

This separation is fundamental to Lightning's privacy model. A forwarding node learns that an HTLC failed downstream (it receives update_fail_htlc) but cannot read why: the failure reason is encrypted to the sender's key. For a deeper look at how onion routing protects payment privacy, see our research on onion routing and Lightning privacy.

Deprecated and Removed Codes

As the BOLT specifications evolve, some failure codes are deprecated or removed. Implementations may still encounter these codes from older nodes on the network:

• invalid_realm (0x4001): removed in 2024 when the realm byte was dropped from the onion format. Older nodes may still return this for malformed onions
• incorrect_payment_amount (0x4010): deprecated in favor of incorrect_or_unknown_payment_details (0x400F) to prevent probing attacks that could distinguish "wrong amount" from "unknown hash"
• final_expiry_too_soon (0x0011): also merged into 0x400F for the same anti-probing reason

The consolidation of these codes into a single incorrect_or_unknown_payment_details response was a deliberate privacy improvement. Previously, an attacker could probe whether a node was the final destination of a payment by sending payments with correct hashes but wrong amounts: if the node returned "wrong amount" instead of "unknown hash," the attacker confirmed it was the intended recipient.

Frequently Asked Questions

What does temporary_channel_failure mean on Lightning Network?

temporary_channel_failure (0x1007) is the most common Lightning payment error. It means a forwarding channel cannot handle the HTLC at this moment, usually because it lacks sufficient outbound capacity. The failure is transient: the channel may have capacity after pending HTLCs resolve. Your node should automatically retry on an alternate route. If you see this error repeatedly on your own channels, consider rebalancing or opening additional channels.

How do I fix "unknown_next_peer" errors?

unknown_next_peer (0x400A) means your routing graph references a channel that the processing node does not have. The channel was likely closed since your graph was last updated. Ensure your node is syncing gossip data from well-connected peers, and consider using route hints when paying invoices from nodes with private channels. This is a permanent failure: do not retry on the same route.

Why do Lightning payments fail with "incorrect or unknown payment details"?

incorrect_or_unknown_payment_details (0x400F) is a catch-all code returned by the final node. It intentionally combines multiple failure reasons (unknown payment hash, wrong payment secret, insufficient amount, expired invoice) into a single response to prevent probing attacks. Check that the invoice has not expired, the payment amount matches what the recipient expects, and you are using the correct payment secret from the invoice.

What is the difference between BOLT #1 errors and BOLT #4 failure codes?

BOLT #1 error (type 17) and warning (type 1) messages are plaintext messages exchanged directly between two connected peers. They affect the channel relationship between those nodes and can trigger force closes. BOLT #4 failure codes are encrypted onion messages that travel backward through a multi-hop payment route: only the original sender can read them. BOLT #1 errors handle channel-level problems; BOLT #4 codes handle payment routing failures.

How do blinded path errors work on Lightning?

When a payment fails within a blinded path, the error is replaced with the generic invalid_onion_blinding (0xC018) code. This prevents the sender from learning which specific hop in the blinded segment failed or why. The tradeoff is reduced debuggability in exchange for stronger receiver privacy: the sender cannot map the internal structure of the blinded route. This code was introduced alongside BOLT 12 offers.

What causes mpp_timeout errors?

mpp_timeout (0x0017) occurs when a multi-part payment recipient does not receive all payment parts within a reasonable time. The recipient holds partial HTLCs waiting for the remaining parts, and if they do not arrive, all parts are failed back. This typically happens when one payment shard encounters routing failures while others succeed. Retry the entire payment: partial amounts are returned to the sender via standard HTLC timeout mechanisms.

Can I see the raw failure code from a failed Lightning payment?

Yes. Most Lightning node implementations expose failure details in their APIs. In LND, check lncli payinvoice output or query lncli trackpayment for the failure_reason field. In CLN, use lightning-cli pay which returns structured failure data including the failing node and error code. LDK exposes failure information through its PaymentPathFailed event. The raw hex failure code maps directly to the BOLT #4 codes listed in this reference.

This reference is for informational purposes only and does not constitute financial or technical advice. Error codes are based on the current BOLT specifications and may change as the protocol evolves. Always consult the latest BOLT specification repository for authoritative definitions.