CLN Onion Message Errors - Fix Routing and BOLT12 Issues

What Are CLN Onion Messages?

Onion messages allow nodes to send encrypted peer-to-peer messages over the Lightning Network without creating payment channels. Used by BOLT12 offers for invoice requests.

Common Errors

• onion_message: peer does not support option_onion_messages
• send_onion_message: no path found to destination
• onion_message_forward: failed to decrypt onion
• fetchinvoice: reply path not reachable

Check Onion Message Support

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

# Check peer support
lightning-cli listpeers | python3 -c "
import json,sys
for p in json.load(sys.stdin)['peers']:
    f = str(p.get('features',''))
    print(p['id'][:20], 'onion_msg:', '14' in f)
"

Enable Onion Messages in Config

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

# Restart lightningd after adding
sudo systemctl restart lightningd

Debug Routing Failures

# Try sending a test onion message
lightning-cli sendonionmessage <peer_id> <message_hex>

# Check logs for forwarding issues
jourналctl -u lightningd | grep -i 'onion_message\|onion-message' | tail -20

# Verify path exists
lightning-cli getroute <dest_node_id> 0 1

BOLT12 Fetch Invoice Failure

# fetchinvoice fails if onion messages are broken
lightning-cli fetchinvoice <offer_string>

# Debug: check if offer's node is reachable
lightning-cli connect <offer_node_id>@<host>:<port>

# If using Tor, ensure tor proxy is running
lightning-cli getinfo | grep address

CLN onion message issues blocking your BOLT12 setup? DM on Nostr for help.