Diagnosing Invoice and Routing Failures

When a Lightning payment fails, the first area to inspect is the invoice and the routing attempt. Common invoice-related failures include expired invoices, incorrect amounts (msats vs sats confusion), and malformed BOLT11 strings. Start by verifying the invoice: decode the BOLT11 invoice with a tool like bolt11-decode or the wallet's decode command (e.g., lncli decodepayreq for LND, lightning-cli decodepay for Core Lightning). Check expiry timestamp, amount, and features field. If an invoice is expired, the sender will get a permanent failure; the only fix is to request a fresh invoice.

Routing failures can be transient or permanent. Check the payer node’s payment log (lncli listpayments, lightning-cli listpayments) to see the failure reason and route attempt details. Look for error types: “TemporaryChannelFailure”, “FeeInsufficient”, “IncorrectOrUnknownPaymentDetails”, “UnknownNextPeer”, or “FinalExpiryTooSoon”. Temporary failures often indicate a liquidity or route fluctuation and are retriable; permanent failures (e.g., malformed invoice) require action from the payee.

Use queryroutes (lncli queryroutes or lightning-cli getroute) with a few different amounts and probe smaller amounts to find possible paths. On LND, enable debuglevel=debug to capture detailed route errors, and examine HTLC-level failure onion replies. For Core Lightning, check gossip, connect, and getroute logs. If you see “deadline exceeded” or “All attempts failed”, try increasing the max_attempts or split into multiple smaller payments (MPP) if the receiver supports it. Always correlate the timestamped logs on both payer and payee when possible to identify mismatched expectations (e.g., payee rejected due to custom invoice metadata checks).

Resolving Liquidity and Channel Constraints

Liquidity imbalances are among the most frequent causes of Lightning payment failures—either the payer lacks outbound capacity or the network path lacks inbound liquidity to the payee. Diagnose channel balances using listchannels or listpeers; tools like RTL, Ride The Lightning, or ThunderHub present inbound/outbound liquidity visually. If your node has insufficient outbound capacity, receive on-chain funds to the node and open new channels, or ask a peer to open a channel to you with inbound capacity.

For routing-specific liquidity, split payments using Multi-Path Payments (MPP) or AMP (if supported). Many wallet clients automatically try MPP for large amounts; if yours doesn’t, manually split into smaller payments. You can also use probe payments (a small-value probe) to discover viable paths without revealing the final payment. Watch for “TemporaryChannelFailure” with channel IDs—this indicates the channel exists but currently lacks the needed liquidity on the forwarding side.

Channel management techniques: reposition liquidity by performing circular rebalancing (send an outbound payment to yourself via an intermediate node to move funds from inbound channels to outbound channels), use automated rebalancers (e.g., thunderhub’s rebalance, autobahn), or use a liquidity marketplace/paid rebalancing service. When opening channels for improved inbound liquidity, choose well-connected watchful peers and set sensible channel sizes; avoid tiny channels that become quickly unusable due to reserve/dust limits. Also ensure fee policies (base fee, ppm) are reasonable—overly high fees can cause routes to drop your node from potential paths. Finally, monitor channel closure and chain confirmations: pending closes reduce available liquidity until resolved.

IndoBet365 Live

Handling Protocol and Compatibility Issues (BOLT11, Feature Bits, MPP)

Protocol mismatches and feature negotiations can silently cause payment failures. BOLT11 invoices carry feature bits that indicate support for MPP, offers, AMP, and other extensions. If the payer’s wallet attempts MPP but the payee invoice lacks the MPP feature bit, attempts to split will fail. Decode invoices and inspect feature bits; ensure both sides run versions supporting the necessary features. For AMP, both payer and payee must advertise and accept AMP in their feature negotiation.

Different implementations handle feature negotiations and error forwarding differently. For example, LND might return different onion failure codes than Core Lightning or Eclair, and some clients expose friendly error messages while others give raw onion errors. If you see errors like “unknown_payment_hash” or “incorrect_payment_amount”, verify the payment hash and preimage expectations. A payment that fails with “IncorrectOrUnknownPaymentDetails” often indicates a mismatch between the invoice hash and the HTLC or the invoice being settled with a different preimage.

Inspect error onion codes in detailed logs to determine whether failures are at the intermediate hop (routing policy, fee, or liquidity) or final hop (invoice mismatch). Some nodes enforce additional invoice constraints (custom TLV fields, expiry thresholds, or routing hints). Ensure routing hints are present if the payee is privately connected or has private channels. When using invoices from custodial services like LightningCrypto, confirm that the service’s invoices comply with common wallets—if the service uses nonstandard TLVs, some wallets may not parse them, leading to failure.

Upgrade nodes to the latest stable releases to get the latest protocol compatibility fixes. When debugging, collect the full failure onion payloads and correlate them with the receiver’s logs (if accessible) to see whether it rejected the HTLC due to unsupported features, preimage checks, or internal policy. If you control the payee, enable detailed invoice logging and consider supporting a broader set of feature bits (carefully, with security considerations) to maximize compatibility.

Network, Node, and Wallet Configuration Troubleshooting

Network-level issues and misconfigurations on nodes or wallets often appear as timeouts, connection rejections, or "unknown next peer" errors. Start by verifying basic node health: check getinfo (lncli getinfo, lightning-cli getinfo) for online status, latest block height, and connected peers count. Ensure your node’s clock is accurate (NTP), because time skew can cause invoice expiry misunderstandings and certificate validation problems. Confirm your node can reach the rest of the Lightning network—use listpeers and peer connectivity checks; a node with few peers or stuck gossip sync will have poor route options.

Firewall and NAT settings matter: if you expect inbound channels, ensure the node’s port is reachable or use a reliable NAT traversal/UPnP solution. For Electrum or mobile wallet users, ensure the wallet’s backend (e.g., a connecting LND node or custodial API) is reachable and not rate-limiting connections. If payments time out with “no_route” or the node cannot find a route, increase gossip_sync intervals, check for network partitions, and consider adding well-connected peers (pubkey and host) to improve routing diversity.

Wallet configuration may impose limits such as max_htlc_inflight, CLTV delta minimums, or fee ceilings. Review config files for LND (lnd.conf) or Core Lightning (config) to ensure sensible defaults for forwarding policy, max in-flight HTLCs, and forwarding fees. For heavy use, tune the forwarding_max_htlcs parameter and consider enabling autopilot or channel balancing services.

Finally, gather diagnostics to present to support if needed: copy the payment failure hash, timestamps, route attempts, node versions, and relevant logs. For custody or merchant integrations like LightningCrypto, include the invoice string, charge ID, and any API response bodies. With these details, support teams can correlate on-server logs and identify whether the failure originated from network, wallet, invoice generation, or service-side enforcement.