LND Invoice Expired — Debug and Prevent Payment Failures

Invoice expiry causes 'invoice expired' or 'UnknownPaymentHash' errors. Here's how to debug and prevent them.

Understand invoice expiry

# Default expiry is 3600 seconds (1 hour)
# After expiry, the payment hash is invalid

# Check an invoice's expiry
lncli decodepayreq <BOLT11_INVOICE> | python3 -c "
import json, sys, datetime
d = json.load(sys.stdin)
expiry = int(d.get('expiry', 3600))
timestamp = int(d.get('timestamp', 0))
expires_at = datetime.datetime.fromtimestamp(timestamp + expiry)
print(f'Expires at: {expires_at}')
print(f'Expiry seconds: {expiry}')
"

Create invoices with longer expiry

# Create invoice that expires in 24 hours
lncli addinvoice --expiry 86400 --amt 10000 --memo 'payment for services'

# Create invoice with no expiry (use with caution)
lncli addinvoice --expiry 0 --amt 10000 --memo 'no expiry'

# Via API (Python)
import codecs, grpc
stub.AddInvoice(ln.Invoice(
    value=10000,
    memo='payment',
    expiry=86400  # 24 hours
))

List and check pending invoices

# List all invoices
lncli listinvoices | python3 -c "
import json, sys, time
d = json.load(sys.stdin)
for inv in d['invoices']:
    state = inv.get('state', '?')
    amt = inv.get('value', 0)
    add_idx = inv.get('add_index', '?')
    if state == 'OPEN':
        creation = int(inv.get('creation_date', 0))
        expiry = int(inv.get('expiry', 3600))
        remaining = (creation + expiry) - time.time()
        if remaining > 0:
            print(f'OPEN idx={add_idx} amt={amt} expires_in={remaining:.0f}s')
        else:
            print(f'EXPIRED idx={add_idx} amt={amt}')
"

Track settled vs expired invoices

lncli listinvoices | python3 -c "
import json, sys
d = json.load(sys.stdin)
states = {}
for inv in d['invoices']:
    s = inv.get('state', 'UNKNOWN')
    states[s] = states.get(s, 0) + 1
for s, count in sorted(states.items()):
    print(f'{s}: {count}')
"

Need invoice/payment debugging help? $9

I debug LND payment failures, expired invoices, and HTLC issues. USDT TRC-20.

→ Service page