CLN Onion Message Errors - Fix Routing and Peer Support Issues

What Are CLN Onion Messages?

Onion messages allow nodes to send arbitrary encrypted messages over the Lightning network without HTLCs. They are used by BOLT12 offers for invoice requests and other peer communication.

Common Errors

• onion_message: no route to destination
• send_onion_message failed: peer does not support onion_messages
• onion_message_forward: unknown next peer
• BOLT12: invoice_request timeout - no response via onion message

Check Onion Message Support

# Check if CLN has onion messages enabled
lightning-cli getinfo | python3 -c "
import json,sys; d=json.load(sys.stdin)
feats = d.get('our_features',{})
print('node_features:', feats.get('node','')[:60])
"

# Check peer support
lightning-cli listpeers | python3 -c "
import json,sys
for p in json.load(sys.stdin)['peers']:
  feats = p.get('features','')
  om = '1' if '0x14' in feats or 'onion' in str(p).lower() else '?'
  print(p['id'][:20], 'onion_msg:', om)
"

Enable Onion Messages in CLN

# In lightningd config (should be on by default in v23+)
experimental-onion-messages

# Restart CLN
sudo systemctl restart lightningd

Send a Test Onion Message

# Send onion message to a peer
lightning-cli sendcustommsg <peer_id> 513 <hex_payload>

# Or use BOLT12 offer flow which uses onion messages internally
lightning-cli fetchinvoice <offer_string> 1000

Troubleshooting Route Issues

• Onion messages require a path of supporting nodes - not all nodes support them yet
• Try with a direct peer first to isolate routing vs feature issues
• Check CLN version: onion messages stable since v23.02

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