Eclair Channel Reestablish Errors: Fix Sync and Reconnect Failures

What Are Channel Reestablish Errors?

When two Lightning peers reconnect after a disconnection, they exchange channel_reestablish messages to sync state. Mismatches cause channels to force-close or get stuck.

Common Error Messages

channel_reestablish failed: commitment number mismatch
peer sent unexpected channel_reestablish
cannot reconnect: local/remote commitmentNumber mismatch
FundingTxNotFound during reestablish

Root Cause 1: Commitment Number Mismatch

Local and remote nodes disagree on how many commitments have been exchanged. Usually caused by data loss or a stale backup restore.

# Check logs for mismatch values
grep 'channel_reestablish' ~/.eclair/eclair.log | tail -20

# Force close the affected channel
eclair-cli forceclose --channelId=CHANNEL_ID

# Monitor state
eclair-cli channels | jq '.[] | select(.channelId=="CHANNEL_ID") | .state'

Root Cause 2: Stale Backup

If you restored from an old backup, your commitment numbers are behind. Your peer will detect this and force-close the channel — this is correct behavior to protect both sides.

# Check for channels stuck in CLOSING
eclair-cli channels | jq '.[] | select(.state | startswith("CLOSING")) | {channelId, state}'

# Confirm peer-initiated close
grep 'RemoteError' ~/.eclair/eclair.log | grep CHANNEL_ID

Root Cause 3: Funding TX Not Found

Eclair cannot find the funding transaction on-chain. Causes: unconfirmed tx, RBF replacement, or reorg.

# Check funding tx
eclair-cli channel --channelId=CHANNEL_ID | jq .data.commitments.commitInput

# Verify on-chain
bitcoin-cli gettransaction TXID

# Force a rescan
eclair-cli audit

Prevention

• Always back up ~/.eclair/eclair.sqlite before stopping your node
• Never restore from backup without verifying it is the most recent state
• Eclair auto-exports SCB to ~/.eclair/channel_backups/ — verify this directory exists
• Set eclair.channel.min-depth-blocks=3 to avoid reorg-related funding issues

Verify SCB Backups

ls ~/.eclair/channel_backups/

# Compare backup count vs active channels
eclair-cli channels | jq 'length'