Troubleshooting
Diagnose by symptom: pairing, agent, PATH, tunnels, Docker, licence, billing, and AppSumo.
Work in this order before opening a ticket:
- Identify the affected machine
- Check whether it is online (website last seen, or local
portpilot status) - Check the agent (Windows services / Linux systemd)
- Check the resource (port, tunnel, Docker, firewall)
- Run Diagnose or
portpilot doctor - Read logs (no tokens)
- Retry
- Contact support if still blocked
Symptom index
| Symptom | Guide |
|---|---|
| Port not appearing | Ports |
| Machine offline / will not pair | Pairing |
| CLI not found | Windows / Linux |
| Service will not start | same + portpilot doctor |
| Tunnel will not connect | Tunnels |
| Firewall action failed | Firewall |
| Docker unavailable | Docker |
| Cloud unavailable | Cloud |
| Licence not recognised | Licensing |
| Billing issue | Billing |
| AppSumo code problem | AppSumo |
Quick table
| Symptom | What to do |
|---|---|
| Pairing code expired | Generate a new one. Codes last about three minutes. |
| Invalid code | Check hyphens. O/0 and I/1 match. Not an AppSumo code. |
| Cloud unreachable | Local ports still work. Check outbound HTTPS to the API. |
| Machine limit | Revoke a machine or upgrade. |
| Already paired | Unpair locally or revoke, then pair again. |
| Linux CLI cannot find the token | New shell, or export PORTPILOT_DATA_DIR=/var/lib/portpilot. |
| Agent down (Windows) | Services PortPilotAgent / PortPilotHelper. Desktop Restart agent. |
| Agent down (Linux) | sudo systemctl restart portpilot-agent (and helper if installed). |
| Desktop cannot reach agent | Wait a few seconds after boot; confirm services. |
| Tunnel create fails | Pro/Cloud entitlement and ngrok API config. Cloudflare is not supported. |
| Firewall mutate fails | Pro entitlement; Linux needs UFW. |
Still stuck? Support or FAQ. Do not send passwords, pairing codes, licence secrets, or card numbers.