Velocity Cannot Connect to a Backend Server

Direct answer

If Velocity accepts a client but cannot connect to a backend, first verify the backend process, IP/port and internal network path. Only troubleshoot player forwarding after the proxy can open the backend connection.

What it means

A proxy logs a backend connect timeout/refusal differently from a modern forwarding secret mismatch. Mixing those stages can lead to unsafe changes to online-mode or firewalls.

Practical example: Example: Connection refused to a backend IP and port means the proxy could not open that TCP socket; a forwarding-secret mismatch happens later after the socket connects. Fix backend listening/bind/firewall first, then re-test modern forwarding. Changing backend online-mode to make a refused TCP connection disappear will not help.

If you are a player

• Report which destination server fails and whether the lobby still works.
• Do not try to connect directly to a protected backend as an alternative login route.

If you run the server

1. Verify the backend reports successful startup and listens on its intended private address/port.
2. Check the matching servers entry in velocity.toml and ensure localhost is used only when the proxy shares that network namespace.
3. From the proxy host, test TCP reachability to the backend with an appropriate diagnostic tool.
4. Once TCP connects, verify Velocity forwarding mode, shared secret and backend Paper configuration.
5. Check firewall rules: allow trusted proxy-to-backend traffic but block public direct backend access.

References

References used to verify the settings and troubleshooting steps in this fix.

• PaperMC: Velocity FAQ
• PaperMC: Velocity player information forwarding
• PaperMC: Velocity security
• PaperMC: Basic troubleshooting

Related fixes and guides