CLN Onion Message Errors - Fix BOLT12 Offer and Routing Issues

What Are CLN Onion Messages?

Onion messages (BOLT 12) allow nodes to communicate off-chain without payment, enabling offers, invoice requests, and async payments. CLN supports them natively.

Common Errors

• onion message: no route to destination
• fetchinvoice: timeout waiting for invoice
• experimental-onion-messages not enabled
• offer: unknown bolt12 feature bits required

Enable Onion Messages

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

# Verify enabled
lightning-cli getinfo | grep -i onion

Create and Pay a BOLT12 Offer

# Create offer (reusable invoice)
lightning-cli offer amount=any description='Lightning consulting'

# Pay an offer
lightning-cli fetchinvoice <offer_string> 10000
lightning-cli pay <invoice_from_fetchinvoice>

Debug Routing Issues

# Check if peer supports onion messages
lightning-cli listpeers | python3 -c "
import json,sys
for p in json.load(sys.stdin)['peers']:
  feats = str(p.get('features',''))
  print(p['id'][:20], 'onion_msg:', '0x101' in feats or '257' in feats)
"

# Onion messages need a path - ensure connected peers
lightning-cli connect <node_id>@<host>:<port>

Need BOLT12 help? DM on Nostr.