Troubleshooting

Step 01

The decoder returns 404 or cannot connect

Check the API health endpoint:

curl -i http://localhost:3001/health

The Rust API should respond with JSON. A Next.js HTML page suggests that the frontend is running on the API port. Use port 3000 for the frontend and 3001 for the API.

Check NEXT_PUBLIC_API_BASE_URL in the frontend environment and restart or rebuild the frontend after changes. If the browser reports CORS errors, ensure ALLOWED_ORIGINS includes the frontend’s exact origin.

Step 02

A port is already in use

On macOS or Linux with lsof installed, inspect the listener:

lsof -nP -iTCP:3000 -sTCP:LISTEN

For Docker containers publishing that port:

docker ps --filter publish=3000

Stop the identified service in its terminal or Docker Desktop, or choose another port. If the frontend origin changes, update the API’s allowed origins too.

Step 03

A QR image will not import

Use a clear image with the whole QR and its surrounding margin visible. Confirm it contains a BOLT11 invoice, uses a supported image format, and fits the size limits. You can paste the invoice text directly to distinguish an image-reading problem from an invoice-validation failure.

Step 04

Samples are expired or the network does not match

The bundled samples are intentionally expired. Polar invoices use regtest, so expecting mainnet will produce a mismatch warning. Select Detect only or the correct expected network. Neither warning prevents inspection.

Step 05

Offline mode tries to contact an API

Remove the environment setting in the terminal session and launch without an API flag:

unset LIGHTNING_API_URL
./target/release/bolt11-decoder

If Cargo’s offline build reports missing dependencies, build once while connected. Running an already-built binary does not require Cargo or dependency downloads.