Troubleshooting Guide ​
FreshDiagnostic Tool ​
Always start troubleshooting with:
bash
ngrok diagnoseThis runs a series of tests to identify connection issues.
Decision Tree ​
Common Issues ​
Installation Issues ​
| Issue | Solution |
|---|---|
ngrok not recognized as command | Add install folder to PATH; open new terminal |
| Download blocked | Add antivirus exception for ngrok executable |
| Permission denied | Run terminal as Administrator |
Connection Issues ​
| Issue | Solution |
|---|---|
| Cannot connect to ngrok service | Check firewall allows outbound port 443 |
| Authentication failed | Verify authtoken with ngrok config check |
| DNS resolution failed | Check internet connectivity; ngrok uses fallback DNS |
| TLS verification failed | Update ngrok to latest version: ngrok update |
| Rate limited | Wait and retry; check account plan limits |
Tunnel Issues ​
| Issue | Solution |
|---|---|
| 502 Bad Gateway | Local service is not running or crashed |
| Connection refused | Wrong port number; verify with netstat -ano |
| ERR_NGROK_8012 | Account tunnel limit reached; close other tunnels |
| Tunnel session expired | Free plan session limit; restart ngrok |
| Slow performance | Check local service performance; upgrade plan for more bandwidth |
Windows Service Issues ​
| Issue | Solution |
|---|---|
| Exit code 5 | Config file not found; verify path in service install |
| Input/output error | Same as exit code 5; check file permissions |
| Service won't start | Check Windows Event Log (eventvwr.msc) |
| Service stops unexpectedly | Check Event Log; verify upstream services |
| Service doesn't start on boot | Verify service is set to "Automatic" startup |
Config File Issues ​
| Issue | Solution |
|---|---|
| YAML syntax error | Run ngrok config check for validation |
| Unknown property | Check you're using the correct config version (v3) |
| Endpoints not starting | Verify indentation; YAML is whitespace-sensitive |
| Config not found | Default: %HOMEPATH%\AppData\Local\ngrok\ngrok.yml |
Network Diagnostics ​
Check if port 443 is accessible ​
bash
# PowerShell
Test-NetConnection connect.ngrok-agent.com -Port 443Check DNS resolution ​
bash
nslookup connect.ngrok-agent.comCheck local service is running ​
bash
netstat -ano | findstr :8080Getting Help ​
- ngrok Status Page: Check for service outages
- ngrok Community: community.ngrok.com
- ngrok Support: support@ngrok.com
- Documentation: ngrok.com/docs