Diagnosing ngrok Tunnels That Appear Up but Cannot Reach Your Local Service

Recognizable Condition

You run ngrok http 8080 (or any TCP tunnel) and the console prints a public URL such as https://abcd1234.ngrok.io. The tunnel status shows online, yet opening that URL in a browser or with curl hangs, times out, or returns connection refused. No request appears in your local server logs.

Quick Cause‑and‑Symptom Reference

Ordered Diagnostic Checks

1. Verify the local service is actually listening.
   Run on the same host:
   

   ss -ltn 'sport = :8080'   # Linux
   netstat -an | findstr :8080   # Windows PowerShell

   Expect a line showing LISTEN on 0.0.0.0:8080 (or 127.0.0.1:8080). If missing, start the service first.
2. Confirm ngrok can bind to that port.
   Start ngrok with verbose logging:
   

   ngrok http 8080 --log=stdout --log-level=debug

   Watch for Unable to bind to port lines. If present, identify the conflicting PID with lsof -i :8080 (Linux/macOS) or Get-Process -Id (Get-NetTCPConnection -LocalPort 8080).OwningProcess (Windows) and stop it.
3. Check that traffic reaches the ngrok client.
   In the ngrok web UI (default http://127.0.0.1:4040) inspect the Requests tab. If the request appears there but the local server logs nothing, the ngrok client received the HTTP request but failed to forward it locally.
4. Test from an external network.
   Use a phone hotspot or a remote VM to curl -v https://abcd1234.ngrok.io. Success from outside but failure locally points to a host‑side firewall or routing issue.
5. Inspect host firewall / antivirus.
   Temporarily allow inbound on the ngrok agent port (default 4443 for the control channel, plus the random local port ngrok opens for the tunnel). Example for ufw:
   

   sudo ufw allow 4443/tcp
   sudo ufw allow 8080/tcp

   On Windows, add an inbound rule for ngrok.exe in Windows Defender Firewall. Retest step 3.
6. Validate plan limits and auth token.
   Run:
   

   ngrok config check

   It prints the account tier and token validity. If you see Free plan limit reached in the console, upgrade or throttle requests.
7. Confirm region setting.
   Explicitly set region to avoid mismatch:
   

   ngrok http 8080 --region=us

   Match the region shown in the dashboard (e.g., us, eu, ap).
8. Check custom‑domain TLS.
   If using a custom domain, ensure the certificate and key are present in ~/.config/ngrok/ and referenced in ngrok.yml:
   

   tunnels:
     myapp:
       proto: http
       addr: 8080
       hostname: app.example.com
       cert_path: /path/to/fullchain.pem
       key_path: /path/to/privkey.pem

   Run ngrok start myapp and verify no SSL errors in the browser.

Fixes Mapped to Findings

• Port conflict – Stop the conflicting process or change the local service port and update the ngrok command.
• Firewall blocking inbound – Add permanent allow rules for the ngrok agent and the local service port; avoid disabling the firewall entirely.
• Free‑plan throttling – Upgrade to a paid plan or implement client‑side back‑off to stay under 40 connections/minute.
• Region mismatch – Explicitly set --region or remove the region directive to let ngrok pick the nearest edge.
• Expired auth token – Generate a new token from the ngrok dashboard and run ngrok config add-authtoken <TOKEN>.
• Custom‑domain TLS errors – Provide a valid, trusted certificate (Let’s Encrypt or a CA‑signed cert). Self‑signed certs only work if you also trust them on the client.

Escalation Criteria

Escalate to ngrok support (or your internal platform team) when:

• All firewall rules are correct, the local service logs show LISTEN, yet the ngrok web UI still shows zero inbound requests after multiple external tests.
• Authentication token is valid per ngrok config check but the agent repeatedly logs authentication failed.
• Custom‑domain TLS is configured with a valid certificate, yet browsers report ERR_CERT_AUTHORITY_INVALID and the ngrok UI shows no certificate errors.
• You suspect a platform‑level issue (e.g., ngrok edge outage) – check the ngrok status page before opening a ticket.

Practical Verification Checklist

1. Start a minimal server: python3 -m http.server 8080 (or npx serve -l 8080).
2. Run ngrok http 8080 --log=stdout and copy the HTTPS URL.
3. From a different network, run curl -I https://<your‑id>.ngrok.io. Expect 200 OK and a Server: SimpleHTTP/0.6 Python/3.x header.
4. Confirm the request appears in the ngrok web UI (http://127.0.0.1:4040) and in the Python server console.
5. If any step fails, refer to the diagnostic table above and apply the corresponding fix.

Limitations & Gotchas

• This guide assumes ngrok 3.x (released 2023). Older 2.x binaries emit different log lines and use a different configuration file location.
• Free‑plan limits are enforced at the edge; they manifest as silent drops, not as local errors.
• IPv6‑only local services need ngrok http --host-header=rewrite 8080 or an explicit addr: '[::1]:8080' in the YAML.
• Corporate proxies that terminate TLS before reaching ngrok can break the control channel; in that case use the --proxy flag or run ngrok inside a VM with direct internet.