CLN Onion Message Errors - Fix BOLT12 and Routing Issues

What Are CLN Onion Messages?

Onion messages allow nodes to send arbitrary data over the Lightning Network without creating payment channels. They underpin BOLT12 offers and blind paths.

Common Errors

• onion_message_failed: no path to destination
• peer does not support onion messages (feature bit 39 missing)
• sendcustommsg: unknown message type 513
• offer: could not find route for reply path

Check Peer Support

# List peers with onion message support
lightning-cli listpeers | python3 -c "
import json,sys
for p in json.load(sys.stdin)['peers']:
  feats = p.get('features','')
  # bit 39 = onion_messages
  supported = int(feats,16) >> 39 & 1 if feats else 0
  print(p['id'][:20], 'onion_msg:', bool(supported))
"

Send a Test Onion Message

# Send raw onion message to peer
lightning-cli sendcustommsg <peer_id> 0201 <hex_payload>

# Or use sendonionmessage (CLN 23.08+)
lightning-cli sendonionmessage '{"hops": [{"id": "<peer_id>", "tlv_payload": {}}]}'

Debug BOLT12 Offer Failures

# Fetch an offer
lightning-cli offer 1000 'Test offer'

# Pay via offer (uses onion messages internally)
lightning-cli payoffer <bolt12_offer> <amount_msat>

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

Requirements

• CLN 0.12.0+ required for onion message support
• Both sender and recipient must support feature bit 39
• Ensure --experimental-offers is set in pre-24.x CLN versions

Running CLN and hitting weird errors? DM on Nostr.