CLN Onion Message Errors - Fix BOLT 12 and Routing Issues

What Are CLN Onion Messages?

Onion messages (BOLT 7) allow nodes to send arbitrary encrypted messages over the Lightning network without opening a channel. Used by BOLT 12 offers for invoice requests.

Common Errors

• onion_message: no path to destination
• sendonionmessage: failed to find route
• fetchinvoice: timeout waiting for invoice
• decode: unknown feature bit 14 (option_onion_messages)

Enable Onion Messages in CLN

# In lightningd config
experimental-onion-messages
experimental-offers

# Restart CLN
systemctl restart lightningd

Test Onion Message Delivery

# Send a test onion message
lightning-cli sendonionmessage \
  <destination_pubkey> \
  '[{"pubkey": "<hop1>"}]' \
  '{"invoice_request": "<bolt12_offer>"}'

# Check if peer supports onion messages
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:', '022e' in f or '022f' in f)
"

Fix: Path Not Found

• Ensure both sender and receiver have experimental-onion-messages enabled
• Try a direct message first (no hops) to isolate routing issue
• Check gossip: lightning-cli listchannels | wc -l (need good graph coverage)
• Use fetchinvoice with --timeout=60 for slow paths

Onion message or BOLT 12 issues? DM on Nostr for help.