LND HTLC Limit Configuration----Prevent Stuck Payments

What Are HTLC Limits?

HTLCs (Hashed Time-Lock Contracts) are the mechanism behind Lightning payments. LND enforces limits on the number and size of concurrent HTLCs per channel to prevent channel overload.

Key HTLC Settings in lnd.conf

# Max number of HTLCs per channel (default: 483)
max-commit-fee-rate-anchors=10

# Per-channel HTLC limit
# Set in channel open or via UpdateChannelPolicy

Check Current HTLC Limits

lncli listchannels | jq '.[].max_htlc_value_in_flight_msat'
lncli getchaninfo --chan_id <channel_id>

Update HTLC Limits via Policy

lncli updatechanpolicy \
  --max_htlc_msat 990000000 \
  --min_htlc_msat 1000 \
  --chan_point <txid>:<output_index>

Common Errors

- "HTLC is too large" — sender exceeded your max_htlc_msat

- "too many pending HTLCs" — channel is at max concurrent HTLC count (483 default)

- Payments stuck in-flight — caused by HTLC timeout or counterparty offline

Best Practice

Set max_htlc_msat to ~99% of channel capacity. Use lncli cancelinvoice to cancel stuck HTLCs when possible. Monitor pending HTLCs with lncli pendingchannels.