Troubleshooting

Common issues and solutions for the CLINK plugin.

Invoice Timeout / No QR Code

Symptom: The checkout page shows "Loading..." indefinitely or the invoice times out without displaying a QR code.

Possible Causes:

1. Node.js not found — The Nostr bridge requires Node.js 22+
2. Offer string invalid — The noffer1... string may be malformed
3. Relay unreachable — The Nostr relay in the offer string may be down
4. Bridge timeout — The Nostr bridge process exceeded 120 seconds

Solutions:

# Verify Node.js is installed and accessible
node --version

# Check if the bridge script exists
ls -la /tmp/btcpay-clink-nostr/clink-bridge.bundle.mjs

# Test the bridge manually
cd src/BTCPayServer.Plugins.Clink
echo '{"noffer":"noffer1...","amountSats":100,"description":"test","expiresInSeconds":60,"timeoutSeconds":30,"additionalRelays":null}' | node nostr/clink-bridge.bundle.mjs request-invoice

Invalid Offer String

Symptom: "Invalid CLINK offer string. It must start with 'noffer1'." error when saving configuration.

Solutions:

• Ensure the full string was copied (no truncation)
• The string must start with noffer1 (not lnbc, lno, etc.)
• The string must be at least 60 characters long
• Generate a fresh offer string from your wallet

Payment Not Confirming

Symptom: Customer has paid the Lightning invoice but BTCPay Server still shows it as unpaid.

Possible Causes:

1. Relay delay — Nostr relays may have propagation delay
2. Polling interval too high — Default 5000ms may be too slow
3. Relay connectivity — The plugin can't reach the relay

Solutions:

• Wait 30-60 seconds for relay propagation
• Reduce the Poll Interval setting (e.g., to 2000ms)
• Add additional relays in the configuration for redundancy
• Check BTCPay Server logs for bridge errors

# Check BTCPay Server logs for CLINK-related entries
# Look for entries with "ClinkLightningClient" or "ClinkNostrBridge"

Node.js Not Found

Symptom: "Nostr bridge script not found" or process fails to start.

Solutions:

# Install Node.js 22+
# macOS
brew install node@22

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version  # Should show v22.x.x or higher

Bridge Process Timeout

Symptom: "Nostr bridge timed out for command 'request-invoice'" error.

Possible Causes:

1. Relay is slow or unresponsive
2. Network connectivity issues
3. The merchant's Lightning node is offline

Solutions:

• Check your network connection
• Try a different relay (add additional relays in config)
• Verify the merchant's Lightning node is online
• Check if the relay is accessible: curl -I wss://relay-url

nDebit Auto-Pay Not Working

Symptom: Subscription invoices aren't being auto-paid despite having an nDebit configured.

Solutions:

• Verify the nDebit string starts with ndebit1
• Check that the buyer email matches exactly (case-insensitive)
• Look for auto-pay errors in BTCPay Server logs
• Ensure the customer's wallet supports nDebit (currently ShockWallet)

# Check the ndebit registry file
cat clink-ndebit-registry.json

# Check the nostr event store
cat clink-nostr-store.json

Plugin Not Loading

Symptom: The CLINK plugin doesn't appear in the store integrations.

Solutions:

• Verify BTCPay Server version is 2.4.0+
• Check that the plugin DLL is in the correct location
• Restart BTCPay Server after plugin installation
• Check server logs for plugin loading errors

# For development, verify the debug plugin path
cat submodules/btcpayserver/BTCPayServer/appsettings.dev.json
# Should contain: { "DEBUG_PLUGINS": "/path/to/BTCPayServer.Plugins.Clink.dll" }

QR Code Not Displaying

Symptom: The payment page shows text instead of a QR code.

Solutions:

• Ensure the client-side JavaScript bundle is built (npm run build)
• Check browser console for JavaScript errors
• Verify the BOLT11 string is valid (starts with lnbc)

Checking Logs

Enable verbose logging by setting the log level for CLINK namespaces:

{
  "Logging": {
    "LogLevel": {
      "BTCPayServer.Plugins.Clink": "Debug",
      "BTCPayServer.Plugins.Clink.Services": "Debug"
    }
  }
}

Add this to appsettings.dev.json or appsettings.json for development/debugging.