Eclair Pathfinding Errors -- Fix Route Calculation and Payment Failures

Eclair uses its own pathfinding algorithm to route payments through the Lightning Network. When pathfinding fails, payments stall or error out. This guide covers the most common Eclair pathfinding issues and how to fix them.

1. No Route Found

Error: RouteNotFound or no route to peer.

Causes: Destination node is offline or unreachable. Insufficient inbound liquidity along any path. Channel capacity too small for payment amount. Fee parameters too restrictive (maxFeePct too low).

Fix: Check destination node connectivity with eclair-cli nodes --nodeId TARGET. Increase maxFeePct or maxFeeBase in eclair.conf. Try a smaller payment to verify route exists. Use eclair-cli findroute to debug path availability.

2. All Routes Exhausted

Error: ExhaustedRoutes — tried all paths but none succeeded.

Causes: High network congestion. Temporary channel liquidity imbalance. Too many failed attempts depleting route cache.

Fix: Wait and retry — liquidity shifts over time. Open a direct channel to the destination. Use keysend to attempt direct payment. Set routerConf.maxRouteLength = 4 in eclair.conf for shorter paths.

3. Fee Too High

Error: payment rejected due to fee exceeding limit.

Fix: Increase maxFeePct in eclair.conf (default 1%, try 3-5%). Use eclair-cli payinvoice --maxFeePct 5 for one-off payments. Check if destination has high-fee routing nodes — use findroute to inspect.

4. CLTV Delta Errors

Error: expiry too far in the future or too close.

Causes: Route includes nodes with very high cltv_expiry_delta. Chain is slow or node clocks are out of sync.

Fix: Set routerConf.maxCltvDelta in eclair.conf. Sync system clock (ntpd/chrony). Check peer CLTV settings with eclair-cli channels.

5. Pathfinding Timeout

Error: pathfinding timed out before finding a route.

Fix: Increase routerConf.pathFindingExperimentConf.maxPathLength. Reduce network graph size by pruning old channels. Restart Eclair to refresh the in-memory graph.

6. Scoring and Penalty System

Eclair uses a scoring system to avoid failed routes. After failures, nodes/channels get penalized and avoided.

If a valid route keeps failing: Clear the penalty cache with eclair-cli disconnect then reconnect. Use routerConf.pathFindingExperimentConf.useLogProbability = false to disable probabilistic scoring temporarily.

Useful Commands

eclair-cli findroute --invoice BOLT11 — find route for invoice. eclair-cli findroute --nodeId TARGET --amountMsat AMOUNT — find route to node. eclair-cli nodes — list known nodes. eclair-cli channels — list your channels with capacity info.

More Lightning troubleshooting guides at: https://telegra.ph/LND-REST-API-Errors--Fix-Auth-TLS-and-Connection-Issues-03-12