CLN CLTV Expiry Errors: Fix Timelock and Expiry Issues

CLN CLTV Expiry Errors: Fix Timelock and Expiry Issues

CLTV (CheckLockTimeVerify) delta errors in Core Lightning prevent payments from completing when timelock requirements aren't met. This guide covers detection and resolution.

Common Error Messages

• cltv_expiry too soon: downstream CLTV delta insufficient
• CLTV expiry delta too low: channel policy violation
• expiry too far in future: upstream timelock too large
• final_cltv_delta mismatch: invoice vs payment parameters

Root Causes

CLTV errors usually stem from: (1) cltv-delta set too low in channel policy, (2) invoice generated with wrong min_final_cltv_expiry, (3) routing through nodes with incompatible timelock requirements, (4) system clock drift affecting block height calculations.

Diagnosis

# Check your node's CLTV delta settings
lightning-cli listconfigs | grep cltv

# Inspect channel policies
lightning-cli listchannels | python3 -c "
import json,sys
chans = json.load(sys.stdin)['channels']
for c in chans[:5]:
    print(c['short_channel_id'], 'cltv:', c.get('delay',0))
"

# Check specific payment failure
lightning-cli paystatus <bolt11>

Fix: Adjust CLTV Delta

# In config/lightningd.conf
cltv-delta=40          # increase from default 6
cltv-final=18          # min_final_cltv_expiry for your invoices

# Restart
systemctl restart lightningd

# Verify new policy propagated
lightning-cli listchannels | grep cltv

Fix: Invoice Parameters

# Generate invoice with explicit CLTV
lightning-cli invoice 1000000 label123 'description' 3600 '' '' 18
#                                                                 ^--- min_final_cltv_expiry

# For BOLT12 offers
lightning-cli offer 1000 'description' '' '' '' '' 18

Fix: Routing Around Incompatible Nodes

# Exclude nodes with bad CLTV policies
lightning-cli pay <bolt11> exclude=[<node_id>/<short_chan_id>]

# Or adjust max_cltv
lightning-cli pay <bolt11> maxdelay=2016

Prevention

• Set cltv-delta=40+ for better routing compatibility
• Monitor via lightning-cli getinfo for block height sync
• Use lightning-cli checkpayment before paying large invoices
• Keep system clock synced with NTP

Need help debugging specific CLN errors? More guides: LND Pathfinding | Eclair Bolt12 | CLN Splicing