Proxy Network

Proxy / Network

Default proxy: Velocity (by the Paper team; TOML config, modern forwarding). Waterfall is in maintenance mode; BungeeCord is legacy. See references/velocity-modern-forwarding.md for the exact forwarding handshake — getting it wrong is the #1 network setup failure.

The forwarding contract (must all line up)

For a Velocity network with modern forwarding:

1. Proxy velocity.toml: player-info-forwarding-mode = "modern" and

forwarding-secret-file = "forwarding.secret".

1. Secret: the proxy's forwarding.secret file contents must exactly equal each

backend's paper-global.yml: proxies.velocity.secret.

1. Backend paper-global.yml: proxies.velocity.enabled: true, matching secret, and

proxies.velocity.online-mode equal to the proxy's online-mode.

1. Backend server.properties: online-mode=false (the proxy handles authentication).
2. Never also set spigot.yml: settings.bungeecord: true — Velocity + BungeeCord forwarding

enabled together stops the backend from starting.

velocity.toml essentials

bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

[servers]
lobby = "127.0.0.1:30066"
survival = "127.0.0.1:30067"
try = ["lobby"]

[forced-hosts]
"play.example.net" = ["lobby"]

[advanced]
compression-threshold = 256
login-ratelimit = 3000

• Backends bind to internal/loopback ports; only the proxy port is public. Firewall the

backend ports so players can't bypass the proxy (which would hit online-mode=false directly — a security hole).

• try sets the initial-connect order; forced-hosts routes by hostname.

Troubleshooting map

| Symptom | Cause → fix | |---|---| | "Unable to connect you… invalid forwarding" | secret mismatch or wrong forwarding mode → align secret + set modern both sides | | Players join as offline UUID / skins broken | backend online-mode=true, or proxies.velocity.online-mode mismatch → set backend online-mode=false, match proxy | | Backend won't start | BungeeCord and Velocity forwarding both enabled → disable one | | Anyone can join backend directly as op | backend port exposed publicly with online-mode=false → firewall to proxy only | | Legacy BungeeCord network | use ip_forward: true + bungeecord: true; do NOT also enable Velocity |

Method

1. Confirm proxy software + version (Velocity 3.5.0-SNAPSHOT is current in 2026).
2. Walk the 5-point forwarding contract above and verify each side.
3. Lock down backend ports.
4. For proxy-level permissions, run LuckPerms on the proxy too (see permissions-helper).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Teddy563
• Source: Teddy563/mcwrench
• License: MIT
• Homepage: https://mcwrench.teddy.bar

Install and usage instructions live in the source repository linked above.