LND HTLC Stuck Payment Debug -- Fix In-Flight Payments

HTLC stuck payments are in-flight payments that are neither settled nor failed. This guide covers diagnosis and resolution.

Identify Stuck HTLCs

lncli listchannels | jq .channels[].pending_htlcs
lncli pendingchannels

Check Payment Status

# List all in-flight payments
lncli listpayments --include_incomplete | \
  jq .payments[] | jq select(.status=="IN_FLIGHT")

Force-Close to Resolve

# Last resort: force close the stuck channel
lncli closechannel --force <funding_txid> <output_index>

After force-close, HTLCs resolve on-chain via timelock expiry. Funds are available after CLTV delta (~144 blocks).

Prevent Stuck Payments

# Set payment timeout in lnd.conf
[routing]
max-htlc-cltv=144
payment-timeout=60s

Cancel Stuck HTLC (if hash known)

# Only works if you control the receiver
lncli cancelinvoice <payment_hash>

Check HTLC Timeout Block

# Check current block height vs HTLC expiry
lncli getinfo | jq .block_height
# Compare with expiry_height in pending_htlcs

Common Causes

- Peer offline: HTLC cannot be resolved until peer reconnects or channel force-closed

- Insufficient fee: payment stuck in routing, retry with higher fee limit

- Circular routing: increase max_hops or use different route

Quick Fix: Retry With Fee Bump

lncli payinvoice --fee_limit_sat=500 <bolt11>

See also: lncli trackpayment <payment_hash> to monitor status in real time.