Velocity Server Running but Players Can't Join

Your Velocity proxy shows as running in the panel, but players cannot join, or they join and get kicked with “Unable to connect” errors. In most cases the cause is a port problem. This guide covers the most common causes and how to fix each one.

How the Ports Work

A Velocity network uses more than one port, and each one must be correct:

Part	What it is	Default port
Velocity proxy	The server players connect to. This is the only address you give to players.	25577 (set in velocity.toml)
Backend server (Paper, lobby, survival, etc.)	The servers behind the proxy. Players should not connect to these directly.	Any free port, such as 25566

Players connect to Velocity, and Velocity connects to the backend servers. If the port is wrong in any step, the connection fails.

Quick Checklist

Go through these in order:

1. The proxy port in velocity.toml matches the port assigned to your server in the panel.
2. No other server is using the same port.
3. The backend server addresses in velocity.toml use the correct IP and port.
4. The backend server is online.
5. The forwarding mode and secret match on the proxy and the backend servers.
6. The port is open in the firewall.
7. Players are using the right address (and port, if it is not 25565).

Cause 1: The Port in velocity.toml Does Not Match Your Allocation

The bind line in velocity.toml must use the port that your host assigned to this server. If it uses a different port, the proxy runs but nobody can reach it.

1. Stop the server.

2. In the panel, open the Network tab and note the port marked as Primary. This is the port players use to reach your server. (You can also see it in the server address on the Console page.)

3. Open the File Manager and edit velocity.toml.

4. Find the bind line and set the port to match:

   bind = "0.0.0.0:25577"

   Replace 25577 with your assigned port.

5. Save the file and start the server.

Note: Keep the IP as 0.0.0.0. Only change the number after the colon.

Cause 2: Port Conflict (“Address Already in Use”)

If two servers try to use the same port, one of them fails to start, or it starts but does not accept connections. The panel may show the server stopping with an exit code right after it starts.

An example of what you might see in the console (your times and numbers will be different):

[20:14:02 INFO]: Booting up Velocity 3.4.0...
[20:14:03 ERROR]: Unable to bind to /0.0.0.0:25577
java.net.BindException: Address already in use
[Pterodactyl Daemon]: Server marked as offline...
[Pterodactyl Daemon]: ---------- Detected server process in a crashed state! ----------
[Pterodactyl Daemon]: Exit code: 1
[Pterodactyl Daemon]: Out of memory: false

Log line	What it means
Address already in use	Another program or server is already using this port.
Exit code: 1	The process stopped because of an error. Here, the port conflict.
Out of memory: false	This is not a memory problem.

How to fix it:

1. Make sure no other service or plugin uses the same port as the proxy. This includes plugins or mods that open their own port, such as Geyser, Dynmap, Plan or a web panel.

2. Make sure the proxy uses the primary port from the panel. Open the Network tab, check which port is marked as Primary, and put that exact port in the bind line of velocity.toml:

   bind = "0.0.0.0:25577"

   Replace 25577 with your primary port.

3. If you have extra ports available, you can add or switch to another port in the Network tab, set it as Primary, and update bind in velocity.toml to match.

4. Restart the server.

Cause 3: Wrong Backend Server Address in velocity.toml

Players can connect to the proxy, but get kicked with a message like “Unable to connect you to lobby” or “Could not connect to a default or fallback server.” This means Velocity cannot reach your backend server.

Open velocity.toml and check the [servers] section:

[servers]
lobby = "203.0.113.10:25566"
survival = "203.0.113.10:25567"

try = ["lobby"]

Check each of these:

• The IP and port are correct for that backend server.
• The name in try = [...] exactly matches a name in the [servers] list.
• The backend server is online in the panel.

An example of the console output when the backend cannot be reached (wording may vary by version):

[20:31:44 INFO]: [connected player] Player1 (/198.51.100.23:40417) has connected
[20:31:46 ERROR]: [server connection] Player1 -> lobby: Connection refused: /203.0.113.10:25566
[20:31:46 INFO]: [connected player] Player1 (/198.51.100.23:40417) has disconnected: Could not connect to a default or fallback server, please try again later.

Log line	What it means
Connection refused	Nothing is listening on that IP and port. The backend is offline, or the port is wrong.
Connection timed out (if you see this instead)	The port is blocked by a firewall, or the IP is wrong.
Could not connect to a default or fallback server	Velocity could not reach any server in the try list.

Cause 3: Forwarding Mode or Secret Does Not Match

If the port is right but players are still kicked, the forwarding settings may not match between the proxy and the backend server.

On the Velocity proxy (velocity.toml):

online-mode = true
player-info-forwarding-mode = "modern"

Velocity keeps its secret in a file called forwarding.secret in the proxy’s folder.

On each Paper backend server:

1. In server.properties, set:

   online-mode=false

2. In config/paper-global.yml, set:

   proxies:
     velocity:
       enabled: true
       online-mode: true
       secret: "paste-the-contents-of-forwarding.secret-here"

3. Save and restart the backend server.

The secret must be exactly the same as the text in forwarding.secret.

Message	What it means
Unable to verify player details	The secret does not match, or forwarding is set up differently on the proxy and backend.
This server requires you to connect with Velocity.	The player joined the backend server directly instead of through the proxy.

Cause 4: Players Are Using the Wrong Address

• Players must connect to the proxy address, not to a backend server address.
• If the proxy runs on a port other than 25565, the address must include the port, for example play.example.com:25577 or 203.0.113.10:25577.
• If you use a domain name, check that it points to the correct IP address. If you want players to connect without typing a port, ask your host or DNS provider about setting up an SRV record.
• Test with the direct IP and port first. If that works but the domain does not, the DNS record is the problem.

Still Not Working?

Open a support ticket and include:

• Your Velocity version and the Minecraft version of your backend servers
• The bind line and the [servers] section from velocity.toml
• The last 30 to 50 lines of the console when a player tries to join
• The server address you are using to connect