Eclair Invoice Errors — Fix Expiry, Routing, and Feature Failures

Common Eclair Invoice Errors

Eclair invoice failures often stem from expiry, routing, or feature negotiation issues. This guide covers the most frequent errors and how to fix them.

1. Invoice Expired

Error: payment_failed / invoice_expired — The invoice's expiry timestamp has passed.

Fix: Regenerate the invoice. Default expiry is 3600s. For long-lived invoices use --expiry 86400 when creating.

2. No Route Found

Error: route_not_found — Eclair cannot find a path to the destination node.

Fix: Check that you have sufficient outbound liquidity. Verify the payee pubkey is reachable via eclair-cli node [pubkey]. Add more channels or use trampoline routing if enabled.

3. Amount Too Small

Error: amount_below_minimum — The payment amount is below the channel minimum HTLC size.

Fix: Use a higher amount or ensure the invoice amount matches your channel htlc_minimum_msat setting. Check with eclair-cli channel [channelId].

4. Feature Negotiation Failure

Error: feature_failure / unknown_mandatory_feature — Remote node requires a feature Eclair doesn't support.

Fix: Update Eclair to the latest version. Check eclair.conf feature flags match your counterparty. For legacy nodes, try disabling optional features.

5. Invoice Already Paid

Error: invoice_already_paid — Attempting to pay an invoice that was already settled.

Fix: Check payment status first: eclair-cli getsentinfo --paymentHash [hash]. Implement idempotency checks in your application before sending payments.

6. CLTV Expiry Delta Too Low

Error: incorrect_cltv_expiry — The CLTV delta in the invoice doesn't meet channel requirements.

Fix: Set min_final_cltv_expiry_delta higher when generating invoices (default 30 blocks). Update eclair.conf: eclair.router.min-final-expiry-delta = 40.

7. Malformed Invoice

Error: invalid_invoice / bech32_error — Invoice string is corrupted or from a different network.

Fix: Verify the invoice prefix (lnbc=mainnet, lntb=testnet). Re-request a fresh invoice from the merchant. Validate with a BOLT11 decoder before sending.

Quick Reference

eclair-cli listinvoices — List all invoices and their status

eclair-cli getreceivedinfo --paymentHash [hash] — Check if incoming payment arrived

eclair-cli getsentinfo --id [uuid] — Check outgoing payment details