Troubleshooting

Start with doctor


proxai-gateway doctor

doctor checks the installation for the failure scenarios listed below and tells you the likely cause and the fix. When in doubt, run it first.

Common issues

Symptom	Likely cause	Fix
Status shows the gateway key was rejected	The key was revoked or rotated in the dashboard	Generate a new key and run `proxai-gateway setup new <key>`
Status shows the daemon is not running	The service was stopped or never started	`proxai-gateway start`
No records are being captured	No recent activity from a supported coding agent	Use one of the supported coding agents, then check the per-agent counters in `proxai-gateway status`
Records pile up as pending / failed	Network or firewall blocking uploads	`proxai-gateway logs --failed` shows the upload errors; buffered records upload automatically once connectivity returns
Dashboard shows no new sessions	Gateway healthy but uploads lagging	Check `proxai-gateway status` upload section; uploads run every 30 seconds when there is connectivity
Warning that the binary is stale	The installed binary is more than 30 days old	`proxai-gateway upgrade`

Linux: the gateway stops when you log out

On Linux the daemon runs as a systemd user service, and user services stop at logout by default. To keep the gateway running across logouts, enable lingering for your account once:


loginctl enable-linger "$USER"

Where the logs live

Platform	Log directory
macOS	`~/Library/Logs/proxai/proxai-gateway/prod/`
Linux	`~/.local/state/proxai/proxai-gateway/log/prod/`
Windows	`%LOCALAPPDATA%\proxai\proxai-gateway\Logs\prod\`

Getting help

When you communicate with ProxAI about a gateway problem, include a diagnostic report:


proxai-gateway doctor --output

The report is written as an HTML file (to your Desktop by default) and is safe to share — it is generated locally and secrets are already redacted. It contains the diagnostic signals needed to resolve your issue quickly.