Troubleshooting
Fix the most common Binboi failures without guessing.
Most tunnel problems reduce to a few buckets: authentication failure, relay connectivity, target-port mismatch, application-level errors, or provider-specific webhook confusion. This guide walks those buckets in a practical order.
Auth
Invalid token or login failure
If the CLI cannot authenticate, nothing after that matters.
Run `binboi whoami` first to confirm the active token still works.
If that fails, create a new token in the dashboard and run `binboi login --token <token>` again.
Confirm `BINBOI_API_URL` points to the correct control plane if you are using a self-hosted or non-default environment.
Connectivity
Tunnel is offline or never connects
A reserved tunnel is not the same thing as an active tunnel.
Make sure the CLI is still running and has not exited after printing the public URL.
Verify that `BINBOI_SERVER_ADDR` points at the correct relay tunnel listener.
Check the relay logs for authentication rejection or session attach failures.
Upstream
Request is not reaching the local app
If the tunnel exists but the app never sees traffic, the usual culprit is the target service rather than the public URL.
Fast local checks
bash
binboi whoami
curl http://127.0.0.1:3000/health
binboi start 3000 my-appMake sure the app is listening on the same port you passed to Binboi.
Check whether the app binds only to a container network interface or to a different host than `127.0.0.1`.
If `curl localhost` fails locally, fix the application first before debugging the relay.
Responses
404 and 500 errors
These errors mean different things, and treating them the same wastes time.
A 404 often suggests the host or route path did not match what your app expects.
A 500 usually means the request reached your application and the application failed internally.
Use request inspection or logs to determine whether the route mismatch happened at the relay or inside your framework router.
Providers
Webhook signature and payload confusion
Webhook failures often look mysterious until you separate delivery from verification.
Confirm the provider is posting to the correct Binboi URL and route path.
Check the signing secret used locally and compare it to the provider configuration.
Verify that your framework is exposing the raw body if the provider signs the raw payload.
Review middleware ordering for anything that could mutate the request before signature verification.
Most common mistake
Network
Region or connectivity issues
When the basics look correct but traffic still feels unreliable, look at the network path.
Reduce variables first: avoid VPN edge cases, corporate proxies, or unusual local firewall rules.
Keep relay and operator reasonably close together, especially when debugging providers with tighter timeouts.
Start with a single known-good node before expanding to more regions or operators.