CLN Onion Message Errors - Fix BOLT12 and Peer Messaging Failures

What Are CLN Onion Messages?

Onion messages allow nodes to send encrypted messages over the Lightning network without payment channels. They're used for BOLT12 offers and peer communication. Errors here often break invoice requests.

Common Errors

• onion_message: no route to destination
• invoice_request failed: onion message delivery failed
• peer does not support onion messages (feature bit 39 missing)
• send_onion_message: unknown next peer

Check Onion Message Support

# Verify CLN has onion messages enabled
lightning-cli getinfo | python3 -c "
import json,sys; d=json.load(sys.stdin)
feats = d.get('our_features',{})
print('onion_messages:', '0x027' in str(feats) or 'option_onion_messages' in str(feats))
"

Enable Onion Messages in Config

# In lightningd config (enabled by default in CLN 23.08+)
experimental-onion-messages

# Verify peer supports it
lightning-cli listpeers | python3 -c "
import json,sys
for p in json.load(sys.stdin)['peers']:
  print(p['id'][:20], 'connected:', p['connected'])
"

Debug Delivery Failures

# Check logs for onion message errors
tail -f ~/.lightning/bitcoin/lightning.log | grep -i 'onion_message\|invoice_request'

# Test BOLT12 offer roundtrip
lightning-cli offer 1000 'test offer'
lightning-cli fetchinvoice <offer_string> 1000

Common Fixes

• Upgrade CLN to 23.08+ where onion messages are stable
• Ensure both sender and recipient nodes have the feature enabled
• Check that intermediate routing nodes also support feature bit 39
• Use direct channel peers for onion message delivery when possible

BOLT12 or onion message issues? DM on Nostr for help.