Troubleshooting

If something's not working, start here. Each section covers a class of failure with the expected symptom, the most likely cause, and the fix.

Install / Update

"Authentication failed" on Test connection

Symptom: SSH test or save fails immediately with "Authentication failed — check username and password".

Likely cause: root SSH login is disabled, or the password is wrong.

Fix: SSH into your server out-of-band, edit /etc/ssh/sshd_config, ensure PermitRootLogin yes (or prohibit-password if you're going key-based later — Proxima needs password auth today), then sudo systemctl reload sshd.

"Connection timed out" on Test connection

Symptom: test hangs for ~15 seconds then fails with timeout.

Likely cause: your VPS firewall blocks inbound from the dashboard's IPs.

Fix: Look at the yellow "Allow these IPs first" panel on your Connect your server card. Add each one to your firewall:

# UFW
ufw allow from <ip> to any port 22

# iptables
iptables -A INPUT -s <ip> -p tcp --dport 22 -j ACCEPT

# Cloud firewall (DigitalOcean, AWS Security Group, etc.)
# Add an inbound rule for port 22 with the dashboard IP as source

"SSH user is not root"

Symptom: test passes connection but fails with "SSH user is not root."

Likely cause: you SSH'd in as a non-root user (despite the form forcing root — this means root@<host> isn't valid on your box).

Fix: Proxima's installer requires root because it writes to /usr/local/bin, places a systemd unit, and restarts the service. Either enable root SSH or wait for key-based + sudo support (on the roadmap).

Install fails on "Download binary"

Symptom: the Download binary step turns red with "Download failed".

Likely cause: the binary URL is wrong or the gated R2 worker rejected the auth.

Fix (admin):

Verify the URL works with the bearer token:

curl -fsSL -I -H "Authorization: Bearer $GEOIP_TOKEN" "<url>"

If that returns 403, the Worker isn't allowing the releases/ prefix. Update the Worker config.
If that returns 404, the binary isn't where the dashboard thinks it is. Re-upload or fix the URL in Admin → Releases.

Install fails on "Verify checksum"

Symptom: Verify checksum turns red with "FAILED" and a mismatch message.

Likely cause: the SHA-256 you registered doesn't match what's actually on R2 (someone re-uploaded, or you copied the wrong digest).

Fix (admin): re-run shasum -a 256 proxima-gateway-linux-amd64 locally and update the release row's SHA-256 field.

Install fails on "Verify service"

Symptom: all earlier steps green, Verify service turns red, expand the log and you see Service did not reach active state.

Likely cause: the binary started, but crashed immediately. Common reasons:

Missing GeoIP databases — but the install step should have downloaded them. Check /etc/proxima-gateway/ on the box for the three .mmdb files; if absent, re-click Install to retry.
Config schema mismatch (running an older binary against a newer config) — try Update now to land on the latest binary.
Port conflict — the proxy is trying to bind a port already in use. Check journalctl -u proxima-gateway -n 50 on the box.
Binary corruption — re-click Install, the SHA check will catch it next time.

"GEOIP_TOKEN env var not set"

Symptom: install fails immediately on the dashboard with this message — no SSH happens.

Likely cause: the dashboard's environment is missing the gated worker auth token.

Fix (admin): add GEOIP_TOKEN=<secret> and GEOIP_BASE_URL=https://geoip.proximagateway.com to the dashboard's .env and restart it.

Operation

Proxy stopped serving traffic

Symptom: clients see connection refused, but the dashboard shows the server as Active.

Step 1: check license status. Look for a banner on /app:

Yellow (Grace) — proxy is fine, contact admin
Red (Expired) — proxy is shutting itself down on each heartbeat; contact admin to Reinstate

Step 2: SSH in and inspect:

systemctl status proxima-gateway
journalctl -u proxima-gateway -n 100

Common findings:

Failed to load config → /etc/proxima-gateway/config.json is malformed. Re-click Install from the dashboard to overwrite it.
Failed to bind port :443 → port already in use by something else (nginx, caddy, the old proxy). Either stop the conflicting service or change the port in the dashboard.
connection refused to backend → the upstream URL in your port config isn't reachable. Test from the box: curl -v <backend_url>.

Heartbeat shows "Last heartbeat: never"

Symptom: install completed successfully but admin's view of the license card shows no heartbeat after several minutes.

Likely cause: the proxy can't reach the dashboard (outbound firewall blocking the dashboard's URL, or dashboard_url in config.json is wrong).

Fix:

SSH to the box, run:
```
curl -v $(jq -r .license.dashboard_url /etc/proxima-gateway/config.json)/api/heartbeat
```
You should see a 401 Missing bearer token response — that means the network path works, the proxy just needs to send its key.
If you see DNS resolution or connection timeouts, fix the outbound firewall.
Check journalctl -u proxima-gateway for heartbeat: send failed lines — they include the underlying error.

Symptom: you clicked Update and the modal said success, but the banner still shows on /app.

Likely cause: the proxy hasn't sent a heartbeat with the new version yet (60 s window).

Fix: wait a minute, then refresh. If still stuck, check the proxy log on the box for startup errors:

journalctl -u proxima-gateway -n 50

If the binary crashed and systemd is restarting it, you'll see repeated "Started" / "Main process exited" lines. Address the underlying error per the Verify service section above.

Getting unblocked

If none of the above match your situation, gather:

The full install log (expand Show log output in the modal, copy)
systemctl status proxima-gateway and journalctl -u proxima-gateway -n 200 from the box
Your installed version (visible on /app)

…and contact your admin.