CLN Onion Message Errors - Fix Routing and Blinded Path Issues

What Are CLN Onion Messages?

Onion messages allow nodes to send encrypted messages over the Lightning network without making payments. Used by BOLT12 offers for invoice requests and other protocols.

Common Errors

• onion_message: no route to destination
• peer does not support onion_messages feature
• onion_message_parse_error: invalid blinded path
• failed to decode onion: hmac mismatch

Enable Onion Messages in CLN

# In lightningd config
experimental-onion-messages

# Verify feature is active
lightning-cli getinfo | python3 -c "
import json,sys
d=json.load(sys.stdin)
feats=d.get('our_features',{})
print('onion_messages:', '0x2803' in str(feats) or 'onion' in str(feats).lower())
"

Test Onion Message Send

# Send a test onion message to a peer
lightning-cli sendcustommsg <peer_id> 0x01C8 00

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

Debug Blinded Path Errors

# Check CLN log for onion message errors
tail -100 ~/.lightning/bitcoin/lightning.log | grep -i 'onion_msg\|blinded\|onion_message'

# Common fix: peer must have direct channel or be reachable via gossip
lightning-cli connect <peer_id>@<host>:<port>

CLN onion message issues? DM on Nostr for help.