Troubleshooting

Troubleshooting

Start here, always: on the agent, run Tunnels → Test player path (or Overview → Test public reachability). It walks the whole chain the way a real player does — DNS, router, firewall, gateway, tunnel, your Minecraft server — and names the hop that failed. That one button answers most of this page.

Second: read the log. Activity (Ctrl+6) is the live tail; on disk it's %APPDATA%\proxyforward\logs\proxyforward.log.

---

Quick index

Symptom	Go to
Players can't connect at all	↓
Connects, then instantly disconnects	↓
Worked on the LAN, fails from the internet	↓
bad_token / authentication rejected	↓
"Another agent is already connected"	↓
Port already in use	↓
The window never appears	↓
SmartScreen blocks the exe	↓
The link keeps dropping and reconnecting	↓
Player names are missing	↓
Avatars are all placeholders	↓
The map / geography says unavailable	↓
The UI shows "—" instead of a number	↓
Analytics screens are empty	↓
Throughput is poor / lag spikes	↓

---

Players can't connect at all

Almost always the network in front of the gateway, not proxyforward.

1. Did you forward both ports? The control port (8474) and the public port (25565). Forgetting the control port is the single most common mistake — see Networking and Firewall.
2. Is there a cloud firewall? On a VPS, the security group / cloud firewall is usually what's dropping the packets, not Windows. Check it.
3. Is the Windows rule in place? proxyforward firewall status, or Settings → System → Firewall rule.
4. Can players actually resolve the hostname you gave them? The address in the pairing code is what the agent dials; the address players type is separate. Both must work from outside.
5. Run Test player path and believe what it tells you.

Connects, then instantly disconnects

The tunnel is fine; the last hop isn't.

• Is your Minecraft server actually running, on the local_addr the tunnel names?
• Did you enable PROXY protocol v2 on the tunnel but not on the server? The server then reads the PP2 header as if it were Minecraft data and drops the connection immediately. Either set proxy-protocol: true in paper-global.yml, or turn PP2 back off. Toggle it off and retry — that's the fastest way to confirm.
• Running Velocity or BungeeCord with IP forwarding? Then PP2 must be off — they're mutually exclusive. See Tunnels.

Worked on the LAN, fails from the internet

You port-forwarded the public port but not the control port (or vice versa). Both. See above.

bad_token / authentication rejected

The agent's token no longer matches the gateway's. The agent stops rather than hammering the gateway — that's deliberate, not a crash.

Usual cause: the gateway's token was rotated (Settings → Security), or its config was recreated. Fix: get a fresh pairing code from the gateway and re-pair — proxyforward pair "<new code>", or paste it in the GUI.

If the certificate changed instead (you deleted gateway.crt/gateway.key, or moved the gateway to a new machine), you'll get a fingerprint mismatch. Same fix: re-pair.

"Another agent is already connected"

Working as designed. Two different agents are using the same pairing code, and proxyforward refuses to let them fight over the tunnel — without this rule they'd kick each other off forever.

• If you copied the config to a second machine, it kept the first machine's setup but got a new identity. Decide which machine should be the agent.
• If you genuinely want to move the agent to a new machine, export a .pfsetup from the old one (Settings → Backup) and import it on the new one — that carries the identity across, so the new machine supersedes the old one cleanly instead of conflicting with it.

Note the same agent reconnecting is always fine — that's the normal reconnect path.

Port already in use

proxyforward names the culprit rather than leaving you guessing:

Port 25565 is in use by java.exe (PID 1234)

• java.exe → that's your Minecraft server. You've probably pointed a gateway's public port at the machine that's already running Minecraft. Use a different public port, or put the gateway elsewhere.
• Another proxyforward.exe → you have an engine already running, very likely the Windows service. Stop it, or just let the GUI attach to it.

The window never appears

The GUI is built as a Windows GUI app, which means it has no console and cannot print an error — a startup failure is silent by design. The error was written down:

%APPDATA%\proxyforward\logs\crash.log
%APPDATA%\proxyforward\logs\wails.log

Look there first. The most common cause is a missing/broken WebView2 runtime — install the Evergreen runtime.

SmartScreen blocks the exe

Expected: the binaries are not code-signed. Rather than telling you to click through the warning on trust alone, releases carry a provenance attestation you can verify:

gh attestation verify proxyforward-<version>-windows-amd64.exe -R xeri/proxyforward

See Installation.

The link keeps dropping and reconnecting

• A flaky uplink is handled: the agent backs off exponentially and reconnects, and jumps the queue the moment Windows says the network is back.
• A laptop sleeping/waking is also handled — resume is detected and reconnects immediately.
• If the link drops on a very regular rhythm even on a healthy network, that's not normal churn; grab the log and open an issue with a redacted diagnostics bundle (Activity → export diagnostics).

You never need to re-pair after a disconnect. If you find yourself re-pairing routinely, something else is wrong — say so in the issue.

Player names are missing

The Players screen needs Minecraft-aware turned on for that tunnel (Tunnels). It's off by default.

If it's on and names still don't appear, sniffing failed to parse that login — which by design never blocks traffic, so players still connect fine. Modded or very unusual clients can do this. Report it with the client/version.

Avatars are all placeholders

• Give it a few seconds on a cold cache.
• Mojang lookups may be off (analytics.mojang_lookups = false) — that's the intended trade-off, see Analytics and Privacy.
• Offline-mode server? Unauthenticated names often don't resolve to real accounts. Nothing is broken.
• Mojang rate-limits; proxyforward backs off rather than hammering them.

The map / geography says unavailable

Geography needs a MaxMind GeoLite2 .mmdb that you supply — nothing is bundled and no geo service is contacted. Point Settings → Analytics at the file. Note the UI distinguishes "not configured" from "failed to load" from "no data yet" — read which one it says. See Analytics and Privacy.

The UI shows "—" instead of a number

That's not a bug — it means no sample yet. proxyforward deliberately shows "—" rather than a fake 0 ms or 0%, because a real zero and a missing measurement are different things and conflating them makes the dashboard lie. It'll fill in once there's a measurement.

Analytics screens are empty

• Attached to the service? The service has its own analytics database in %ProgramData%\proxyforward\. Stats collected before you installed the service are in your user directory and won't appear.
• Otherwise, check the log for analytics: database unavailable — a database that can't be opened is set aside and recreated, and the tunnel keeps running regardless.

Throughput is poor / lag spikes

Check the boring things first: the gateway's own uplink, and whether the gateway VPS is CPU-throttled. All player traffic is relayed through it, so the gateway's upload speed is your server's effective upload speed for every player.

The relay itself is held to a throughput and latency floor that CI enforces on every commit, so a regression there would fail the build — but your gateway's network is not something CI can test.

---

Still stuck?

Open an issue and attach a diagnostics bundle (Activity → export diagnostics). It's redacted by design — secrets, hostnames, IPs and player identities are stripped — so it's safe to post publicly. Say what you expected, what happened, and what Test player path reported.

Before you file: check Not Yet Implemented. A few settings in the UI are stored but don't do anything yet, and it's not worth your time debugging one of those.