Lightning Troubleshooting: Failed Transactions

Reading Time: 12 minutes

Lightning Network payments fail. Channels force-close at the worst times. Your node shows errors you’ve never seen. This guide covers the most common Lightning payment failures, their root causes, and exactly how to fix them using real diagnostic commands.

Whether you’re running LND, CLN, or Eclair, transaction failures share common patterns. Understanding these patterns turns frustrating errors into solvable problems. This is not theoretical — every failure mode described here comes from real node operation experience.

Common Payment Failures and Error Codes

Lightning payment failures return specific error codes. Each code points to a different underlying problem. Here are the most frequent failures you’ll encounter and what they actually mean.

FAILURE_REASON_NO_ROUTE

This is the most common payment failure. Your node cannot find a path through the network to reach the destination. The payment never leaves your node.

Common causes:

• No channels have sufficient outbound liquidity for the payment amount
• The destination node is offline or has no public channels
• Intermediate routing nodes along all possible paths are offline
• Your node’s channel graph is outdated or incomplete
• The payment amount exceeds the maximum HTLC size on available routes

Diagnosis:

First, check your outbound liquidity across all channels:

lncli listchannels | jq '[.channels[] | select(.active==true)] | map({alias: .peer_alias, local: .local_balance, remote: .remote_balance, capacity: .capacity}) | sort_by(-.local | tonumber)'

This shows your active channels sorted by available outbound (local) balance. If no single channel has enough outbound liquidity, the payment cannot route in a single hop — though multi-path payments (MPP) can split it across channels.

Check if the destination is reachable at all:

lncli getnodeinfo --pub_key=DESTINATION_PUBKEY

If this returns an error, the destination node either doesn’t exist in your graph or has no public channels. Verify your graph is current:

lncli getnetworkinfo

Compare num_nodes and num_channels against known network stats. If your numbers are significantly lower, your graph needs updating. Restarting your node or waiting for gossip propagation usually resolves this.

Solutions:

• Open a direct channel to the destination or to a well-connected node near them
• Use Lightning Loop to rebalance existing channels and move liquidity outbound
• Enable multi-path payments in your wallet configuration if not already active
• Reduce payment amount and send in smaller chunks if MPP isn’t available
• Wait and retry — temporary routing node outages resolve themselves

FAILURE_REASON_INSUFFICIENT_BALANCE

Your node found a route but doesn’t have enough funds in the required channel to push the payment through. This differs from NO_ROUTE because a path exists — you just can’t use it.

Common causes:

• Channel reserve requirements consume part of your balance (typically 1% of channel capacity)
• In-flight HTLCs tie up liquidity that appears available but isn’t spendable
• Routing fees along the path push the total above your available balance
• Pending channel updates haven’t been reflected in your balance yet

Diagnosis:

Check pending HTLCs that may be locking up funds:

lncli listchannels | jq '.channels[] | select(.pending_htlcs | length > 0) | {chan_id: .chan_id, alias: .peer_alias, pending_htlcs: .pending_htlcs}'

Review your actual spendable balance vs. displayed balance:

lncli walletbalance
lncli channelbalance

The local_balance in channelbalance minus unsettled_local_balance gives your true available outbound. Channel reserves further reduce this. For a 1M sat channel, expect roughly 10,000 sats locked as reserve that you can never spend through that channel.

Solutions:

• Wait for pending HTLCs to resolve (usually under 10 minutes)
• Account for reserves and fees when calculating available balance — your real spendable amount is always less than your channel balance shows
• Open larger channels to minimize the relative impact of reserve requirements
• Use proper channel management to keep balanced liquidity

FAILURE_REASON_TIMEOUT

The payment was sent but no confirmation came back within the HTLC timeout period. The funds are in limbo — they’ll either complete or return, but you have to wait.

Common causes:

• An intermediate node went offline while forwarding the payment
• The destination node received the HTLC but hasn’t settled it
• Network congestion is causing delayed forwarding along the route
• A node in the path has a slow or overloaded implementation

Diagnosis:

Check for in-flight payments:

lncli listpayments --include_incomplete | jq '.payments[] | select(.status=="IN_FLIGHT") | {hash: .payment_hash, amount: .value_sat, creation_date: .creation_date}'

Examine the specific payment’s HTLC status:

lncli trackpayment PAYMENT_HASH

This gives real-time updates on the payment’s progress through the network. If the HTLC is stuck at a specific hop, you’ll see which node is holding it.

Solutions:

• Wait for the HTLC timeout to expire — funds will return automatically after the timelock
• Do NOT send a duplicate payment while one is in-flight (risk of paying twice)
• If consistently happening with a specific peer, consider closing that channel
• Increase your HTLC timeout settings for future payments if timeouts are too aggressive
• After the stuck payment resolves, retry using a different route by excluding the problematic node

FAILURE_REASON_ERROR (Generic Forwarding Errors)

This catch-all category includes errors returned by intermediate routing nodes. The most common sub-errors:

• FEE_INSUFFICIENT: Your node calculated a route using outdated fee data. The routing node’s fees have increased since your last graph update.
• CHANNEL_DISABLED: A channel along the route has been disabled by one of its peers, often temporarily during maintenance.
• TEMPORARY_CHANNEL_FAILURE: The forwarding node can’t process the HTLC right now. Usually a transient liquidity or capacity issue on their end.
• INCORRECT_CLTV_EXPIRY: The CLTV (CheckLockTimeVerify) delta doesn’t match what the routing node requires. Your graph data for that node’s policy is stale.

Most of these resolve on retry because your node updates its graph with the error information and picks a different route. If a specific error persists, run lncli queryroutes --dest=PUBKEY --amt=AMOUNT to see what routes your node is attempting to use.

Channel Issues: Force Closures and Stuck Channels

Channel problems cause the most stress for node operators because they involve on-chain transactions, waiting periods, and locked funds. Understanding force closures is essential for anyone running a Lightning node.

Force-Closed Channels

A force closure happens when one peer unilaterally broadcasts the latest channel state to the blockchain. This bypasses the cooperative close process and triggers a timelock on your funds.

Why channels get force-closed:

• Your peer’s node went offline for an extended period and your node gave up waiting
• Your own node experienced downtime and your peer force-closed to recover their funds
• A pending HTLC is about to expire on-chain, forcing a closure to claim it
• Channel state became inconsistent between peers (rare but serious)
• You or your peer deliberately force-closed due to unresolvable routing issues

Checking pending force closures:

lncli pendingchannels | jq '.pending_force_closing_channels[] | {channel_point: .channel.channel_point, limbo_balance: .limbo_balance, blocks_til_maturity: .blocks_til_maturity, recovered_balance: .recovered_balance}'

The blocks_til_maturity field tells you how many more blocks until your funds are spendable. For the initiator of a force close, this is typically 144 blocks (~1 day). If your peer force-closed on you, your funds should be available sooner, but any pending HTLCs add complexity.

Waiting-close channels:

lncli pendingchannels | jq '.waiting_close_channels'

These are channels where a closing transaction has been broadcast but not yet confirmed. During high-fee periods, this state can persist for hours or days. Your node’s watchtower ensures your peer can’t broadcast an old state while the close is pending.

Zombie Channels

Zombie channels appear active in your channel list but haven’t had a graph update in over two weeks. They won’t route payments and waste connection resources.

lncli listchannels | jq '[.channels[] | select(.active==false and .private==false)] | length'

If you have many inactive public channels, consider closing them cooperatively to free up on-chain funds for productive channels. Before closing, attempt to reconnect:

lncli connect PEER_PUBKEY@ADDRESS:PORT

If the peer consistently can’t be reached, a cooperative close via lncli closechannel --chan_point=FUNDING_TXID:OUTPUT_INDEX is the cleanest resolution.

Liquidity Problems

Liquidity management is the operational core of running a Lightning node. Most payment failures trace back to liquidity imbalances. For a comprehensive treatment of this topic, see our Lightning routing optimization guide.

Depleted Outbound Liquidity

After receiving many payments, your channels fill up on the remote side. You have inbound capacity but can’t send. This manifests as NO_ROUTE or INSUFFICIENT_BALANCE for outgoing payments.

Diagnosis:

lncli listchannels | jq '.channels[] | select(.active==true) | {alias: .peer_alias, local_pct: ((.local_balance|tonumber) / ((.local_balance|tonumber) + (.remote_balance|tonumber)) * 100 | floor)} | select(.local_pct < 20)'

This shows active channels where your local (outbound) balance is below 20% of capacity. These channels need rebalancing.

Rebalancing options:

• Circular rebalance: Send a payment to yourself through the network: out through a depleted channel, back in through a full one. Tools like bos rebalance (Balance of Satoshis) automate this.
• Loop Out: Use Lightning Loop to send funds from Lightning to an on-chain address, freeing up inbound capacity on the source channel.
• Spend Lightning: The simplest rebalance — actually spend sats over Lightning to shift liquidity outward.

Depleted Inbound Liquidity

The opposite problem: you’ve sent many payments, channels are full on your side, and you can’t receive. Merchants and service providers hit this frequently.

Solutions:

• Loop In: Send on-chain funds into a Lightning channel via submarine swap
• Request inbound channels: Services like LN+ and Magma offer inbound liquidity
• Open new channels: Fresh channels start with 100% outbound on your side, giving your peers inbound toward you
• Drain channels: Spend or rebalance to push local balance out

Unbalanced Channels Causing Routing Failures

If you route payments for others, channel balance directly affects your routing revenue. A channel depleted in one direction can’t forward payments that direction. Monitor your routing success rate:

lncli fwdinghistory --start_time=-30d | jq '.forwarding_events | length'

Compare this against failed forward attempts in your logs to calculate your routing success rate. A healthy routing node maintains most channels between 25-75% local balance. For more on optimizing fees and liquidity, check our Lightning fees guide.

Node Connectivity Issues

Connectivity problems prevent your node from communicating with peers, propagating gossip, and forwarding payments. They’re often the hidden cause behind what looks like a routing or liquidity problem.

Tor Connectivity

Many home Lightning nodes run behind Tor for privacy. Tor adds latency and occasional reliability issues.

Common Tor problems:

• Tor circuit establishment fails, preventing peer connections
• Onion service descriptor publication fails, making your node unreachable
• High latency causes HTLC forwarding timeouts

Check Tor status:

systemctl status tor
# Check if your node's onion address is reachable
torsocks curl -s https://check.torproject.org/api/ip

If Tor is down, restart it: sudo systemctl restart tor. Persistent issues may require clearing Tor’s data directory and letting it rebuild circuits.

Hybrid mode: Consider running your node in hybrid mode (both Tor and clearnet) if privacy requirements allow it. This dramatically improves connectivity and payment reliability while still offering a Tor endpoint for privacy-focused peers.

Peer Disconnections

Frequent disconnections from specific peers cause payment failures and can trigger force closures if prolonged.

lncli listpeers | jq '.peers[] | {pubkey: .pub_key, bytes_recv: .bytes_recv, ping_time: .ping_time, sat_sent: .sat_sent}'

High ping times (above 5 seconds) indicate connectivity problems. If a peer consistently shows high latency or drops offline, the channel may not be worth maintaining.

Database and Disk Issues

LND’s channel database (channel.db) can grow large and cause performance problems. A corrupted database is one of the worst scenarios for a Lightning node operator.

# Check database size
ls -lh ~/.lnd/data/graph/mainnet/channel.db

# Check disk space
df -h /

If channel.db exceeds 1GB, consider compacting it during scheduled downtime. Always maintain current SCB (Static Channel Backup) files — these are your recovery lifeline if the database corrupts:

lncli exportchanbackup --all --output_file=/path/to/backup/channel-backup-$(date +%Y%m%d).backup

Prevention Tips

Most Lightning failures are preventable with good operational practices. These habits separate reliable nodes from problematic ones.

Monitoring and Alerts

• Balance monitoring: Set up alerts when any channel drops below 10% or above 90% local balance. Tools like ThunderHub, RTL (Ride The Lightning), and LNDmon provide dashboards and notification options.
• Uptime monitoring: Use a simple cron job or external service to ping your node. If uptime drops below 99%, investigate connectivity issues before they cause force closures.
• Disk space alerts: Run out of disk space and your node crashes ungracefully, risking database corruption. Monitor disk usage and set alerts at 80% capacity.
• Backup automation: Script daily SCB exports to an off-node location. If your node hardware fails, SCB backups let you recover funds from all channels.

Channel Selection

• Connect to well-maintained, high-uptime nodes — check their track record on amboss.space or 1ML before opening channels
• Avoid opening channels smaller than 500,000 sats — small channels have proportionally high reserve requirements and limited routing utility
• Diversify your peer set across different node implementations, geographic regions, and network positions
• Open channels during low-fee periods to minimize the on-chain cost of channel creation

Regular Maintenance

• Update your node software promptly — LND, CLN, and Eclair releases often fix routing bugs and improve payment reliability
• Review and close zombie channels monthly to free up capital
• Rebalance proactively rather than waiting for payments to fail
• Test your backup restoration process at least once — an untested backup is not a backup

Fee Policy

Incorrect fee settings cause indirect failures. Fees too high mean nobody routes through you (reducing your graph presence). Fees too low attract liquidity draining. Start with moderate fees and adjust based on actual routing volume. Our fee guide covers the economics in detail.

Emergency Recovery Procedures

When things go seriously wrong, knowing the recovery steps prevents panic-driven mistakes.

Node Won’t Start

1. Check logs first: journalctl -u lnd --since "1 hour ago" -n 200
2. Common cause: corrupted wallet database. Try lncli unlock manually.
3. If the database is corrupted, do NOT delete it. Copy it to a safe location, then attempt repair.
4. If repair fails, restore from SCB backup. This triggers force-closes on all channels but recovers funds.

Stuck Pending Channel Open

A channel funding transaction was broadcast but hasn’t confirmed, and the channel is stuck in a pending state.

lncli pendingchannels | jq '.pending_open_channels'

If the funding transaction has too low a fee, you can use CPFP (Child Pays For Parent) to bump it if your LND version supports it. Otherwise, wait for the transaction to either confirm or fall out of the mempool.

Recovering After Extended Downtime

If your node was offline for days, channels may have been force-closed by peers. After restarting:

1. Let the node fully sync the blockchain and channel graph
2. Check lncli pendingchannels for any force-closed channels
3. Verify your on-chain balance includes recovered funds: lncli walletbalance
4. Reconnect to remaining peers and assess which channels survived
5. Consider opening new channels to replace lost ones, following the fundamentals of Lightning channel selection

Frequently Asked Questions

My payment failed with NO_ROUTE but the destination exists. What gives?

Your node can see the destination in its graph but cannot construct a viable path with sufficient liquidity. This usually means your outbound capacity is too low or too fragmented. Try: (1) rebalancing your largest channel to increase outbound, (2) splitting the payment with MPP if your wallet supports it, or (3) opening a channel to a node that’s well-connected to the destination’s neighborhood.

A force-close happened and my funds show “limbo_balance.” Are they lost?

No. Limbo balance means the funds are locked in a time-locked on-chain transaction. They’ll become spendable after the timelock expires — typically 144 blocks (about 1 day) if you initiated the force close, or faster if your peer did. Check lncli pendingchannels for the blocks_til_maturity countdown. The funds are safe, just temporarily inaccessible.

How do I prevent force closures?

Maintain high uptime (99%+), keep your node software updated, ensure stable internet connectivity, and monitor disk space. Most force closures happen because a node went offline for too long. Running a watchtower protects against your peer broadcasting old channel states during your downtime, but it doesn’t prevent the force closure itself.

Should I use keysend or regular invoices for payments?

Regular invoices are more reliable because the destination explicitly creates the payment parameters. Keysend (spontaneous payments) can fail if the destination doesn’t support it or if probe-based routing decisions are needed. For routine payments, always prefer invoices. Keysend is useful for tips and donations where requesting an invoice isn’t practical.

My channel database is huge. Can I safely compact it?

Yes, but with precautions. Stop your node, create a full backup of the database, then use lncli compactdb (available in newer LND versions). Always export an SCB backup before any database operation. If compaction fails, you can restore from the backup. Never compact while the node is running — this guarantees database corruption.

What’s the difference between a cooperative close and a force close?

A cooperative close requires both peers to be online and agree on the final balance split. It produces a single on-chain transaction with no timelocks — funds are immediately spendable after confirmation. A force close is unilateral: one peer broadcasts the commitment transaction, triggering timelocks and potentially higher on-chain fees. Always prefer cooperative closes when possible.

Payments keep failing through one specific channel. Should I close it?

First, check if the issue is liquidity (rebalanceable) or the peer’s reliability (systemic). Run lncli listchannels | jq '.channels[] | select(.chan_id=="CHANNEL_ID")' to check the channel’s status, uptime, and pending HTLCs. If the peer is consistently offline or unresponsive, closing the channel and reopening with a more reliable peer is the better long-term decision. If it’s just a balance issue, rebalance instead.

{“@context”: “https://schema.org”, “@type”: “FAQPage”, “mainEntity”: [{“@type”: “Question”, “name”: “My payment failed with NO_ROUTE but the destination exists. What gives?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “Your node can see the destination in its graph but cannot construct a viable path with sufficient liquidity. This usually means your outbound capacity is too low or too fragmented. Try: (1) rebalancing your largest channel to increase outbound, (2) splitting the payment with MPP if your wallet supports it, or (3) opening a channel to a node that’s well-connected to the destination’s neighborhood.”}}, {“@type”: “Question”, “name”: “A force-close happened and my funds show “limbo_balance.” Are they lost?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “No. Limbo balance means the funds are locked in a time-locked on-chain transaction. They’ll become spendable after the timelock expires — typically 144 blocks (about 1 day) if you initiated the force close, or faster if your peer did. Check lncli pendingchannels for the blocks_til_maturity countdown. The funds are safe, just temporarily inaccessible.”}}, {“@type”: “Question”, “name”: “How do I prevent force closures?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “Maintain high uptime (99%+), keep your node software updated, ensure stable internet connectivity, and monitor disk space. Most force closures happen because a node went offline for too long. Running a watchtower protects against your peer broadcasting old channel states during your downtime, but it doesn’t prevent the force closure itself.”}}, {“@type”: “Question”, “name”: “Should I use keysend or regular invoices for payments?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “Regular invoices are more reliable because the destination explicitly creates the payment parameters. Keysend (spontaneous payments) can fail if the destination doesn’t support it or if probe-based routing decisions are needed. For routine payments, always prefer invoices. Keysend is useful for tips and donations where requesting an invoice isn’t practical.”}}, {“@type”: “Question”, “name”: “My channel database is huge. Can I safely compact it?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “Yes, but with precautions. Stop your node, create a full backup of the database, then use lncli compactdb (available in newer LND versions). Always export an SCB backup before any database operation. If compaction fails, you can restore from the backup. Never compact while the node is running — this guarantees database corruption.”}}, {“@type”: “Question”, “name”: “What’s the difference between a cooperative close and a force close?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “A cooperative close requires both peers to be online and agree on the final balance split. It produces a single on-chain transaction with no timelocks — funds are immediately spendable after confirmation. A force close is unilateral: one peer broadcasts the commitment transaction, triggering timelocks and potentially higher on-chain fees. Always prefer cooperative closes when possible.”}}, {“@type”: “Question”, “name”: “Payments keep failing through one specific channel. Should I close it?”, “acceptedAnswer”: {“@type”: “Answer”, “text”: “First, check if the issue is liquidity (rebalanceable) or the peer’s reliability (systemic). Run lncli listchannels | jq ‘.channels[] | select(.chan_id==”CHANNEL_ID”)’ to check the channel’s status, uptime, and pending HTLCs. If the peer is consistently offline or unresponsive, closing the channel and reopening with a more reliable peer is the better long-term decision. If it’s just a balance issue, rebalance instead.”}}]}