When someone cannot join your server, the error message already tells you where the problem is; you only need to know how to read it. This guide walks through the common connection messages on Minecraft Java and Bedrock, explains what each means according to the official documentation, and lists what to check in order. It is written for servers on hosting panels, where ports are rarely the default and that alone explains half of the cases.
First: three checks that solve most of them
- Is the server up and fully started? Read the console. Until the
Doneline appears nobody can join, and a modpack server can take several minutes. - Is the address exactly the one from the panel? IP and port. On Pterodactyl and similar panels the port is almost never 25565; a player who types only the IP connects to the default port, where nothing listens. The fix is a subdomain with an SRV record (below).
- Does the player's version match the server's? A 26.3 client does not join a 1.21.x server without ViaVersion, and the reverse is also true.
The server status tool runs the first two checks from the outside: if it responds, the problem is on the client or its network; if it does not, it is the server or the address.
Java errors, one by one
"Connection refused" (io.netty.channel.AbstractChannel$AnnotatedConnectException)
Literally: nothing is listening on that IP and port. The Minecraft wiki puts it the same way. In order of frequency: the server is off or still starting; the port is wrong (check 2 above); the IP belongs to another server or changed; or, on a home server, someone turned the firewall off instead of forwarding the port. On a host, check the console and the address; if both are right, open a ticket, because then it is the provider's network.
"Connection timed out"
Here something is on the other side, but a firewall is dropping the connection without answering. On a home server that is the classic unforwarded router port. On hosting it is usually something else: the player is on a network that blocks the port (schools, offices, some mobile carriers), an antivirus with "network protection", or a VPN cutting the traffic. Test from another connection (mobile data) to isolate it.
"Outdated server! I'm still on X" / "Outdated client! Please use X"
The first appears when the client is newer than the server, the second when it is older. It is not a fault: Minecraft does not allow mismatched versions. Fixes: everyone on the same version (selectable in the launcher), update the server with a backup first, or install ViaVersion (plus ViaBackwards for older clients) if you want several versions at once.
"Failed to verify username!"
The server runs online-mode=true and could not verify the player's session with Mojang. Causes: an unofficial launcher on a premium server; an expired launcher session (restart launcher and game); a recent name change; or Mojang's authentication servers being down, which hits everyone at once. If the server sits behind a proxy (Velocity or BungeeCord), this error on join usually means a backend still has online-mode=true when it should be false; the network guide covers that.
"Invalid session (Try restarting your game and the launcher)"
The client's session token expired or is invalid. Player-side: restart launcher and game; if it persists, log out of the launcher and back in.
"Took too long to log in"
The login handshake exceeded the server's timeout. Slow networks, slow authentication servers, and above all large modpacks where the client takes a while to negotiate mods. On Velocity networks with Forge backends, the official FAQ recommends raising read-timeout in velocity.toml and -Dfml.readTimeout on the backend to the same value.
"Timed out" mid-game
The client stopped answering keepalive packets for 30 seconds: micro-drops on the player's connection, flaky Wi-Fi, or on the server side a long Java garbage-collection pause that freezes the process. One player means their network; everyone at once means look at TPS and memory. Purpur has an option (use-alternate-keepalive) that avoids kicking over a single lost packet.
"Internal Exception: java.io.IOException: An existing connection was forcibly closed by the remote host"
The TCP connection was closed from the other side: the server restarted or crashed at that moment, an oversized packet (plugins sending huge inventories, resource packs), or a network drop in between. It is a generic symptom: read the server console at the exact time of the disconnect.
"The server responded with an invalid server key"
Per the wiki, outdated, unrecognized or modded server or client. Typically a large version gap or a modified client. Align versions.
"Failed to bind to port" (seen by the admin, not the player)
The server cannot open its port at startup. Documented causes: server-ip contains an IP that is not on that machine (leave it blank; your public IP does not go there), another process already uses the port (a second server, a duplicate Geyser), or the port is not the one the panel assigned.
Java version errors at startup
UnsupportedClassVersionError ... class file version 69.0 and similar mean the installed Java is older than the server needs. Official reference: Minecraft 1.18 to 1.20.4 needs Java 17; 1.20.5 to 1.21.11 needs Java 21; and from 26.1 (March 2026) Java 25. On a panel you switch the server's Java image.
Bedrock errors
"Unable to connect to world"
The star error of Bedrock and Geyser, and it leaves no trace in the console. The Geyser docs attribute it to four things: the Bedrock port is not forwarded for UDP (TCP only does not work; Geyser uses the port over both), a firewall on the host, a wrong IP or port (on Bedrock you enter the Java server's IP and Geyser's port, 19132 by default, in a separate field), or the console connection method. If the server is not behind a service like TCPShield, check that the proxy-protocol option in Geyser's advanced config is off.
"Outdated Geyser proxy! This server supports the following Bedrock versions: …"
The player's Bedrock game is newer than the installed Geyser supports. It happens with every Bedrock update. Fix: update Geyser.
"Outdated server! I'm still on 1.x" seen by a Bedrock player
Geyser presents itself to the Java server as a client of the newest version it supports; if your Java server is behind, Geyser cannot join. Update the server or install ViaVersion on it.
"Invalid IP address!" on Bedrock
Bedrock does not understand SRV records. If you handed out a subdomain that only works through SRV, Bedrock players need the IP (or a subdomain with an A record) and the port typed into their port field.
"Stuck on Locating Server"
An outdated Java server relative to Geyser, or a network problem with large packets: the docs suggest lowering mtu in Geyser's advanced config in steps of 100.
Consoles (Xbox, PlayStation, Switch)
They have no field to add an external server. Players join through a DNS trick or a small helper server that redirects them. It is not a fault of your server; it is the procedure, and support walks each player through the method for their console.
Non-standard ports and SRV records: the hidden cause
On a Pterodactyl host your server may be at IP:25580. Hand out only the IP and Java players go to 25565 and see "Connection refused". Two ways out:
- Hand out IP and port together (
IP:25580). Works, but every change means telling everyone. - A subdomain with an SRV record: in your DNS, a
_minecraft._tcp.play.yourserver.comrecord pointing at the real host and port. Java players typeplay.yourserver.comwith no port. Bedrock does not read SRV: give those players an A record plus Geyser's UDP port.
Panels usually provide a free subdomain with the SRV already set; use it instead of raw IPs, and when you change providers you only update DNS, as explained in the migration guide.
When everyone disconnects at once
If several players see the error at the same moment, it is no longer one person's network. Usual causes: the server crashed or restarted (console), a long memory pause (the process freezes and kicks everyone on timeout), a DDoS attack (on our plans protection is included and you see it in the panel), or the node's IP changed. A Spark report taken at that moment usually shows whether the cause was inside the server.
Quick summary
- Refused: nothing at that IP:port. Console and address.
- Timed out: something blocks the connection. Firewall or the player's network.
- Outdated: version mismatch. Align or ViaVersion.
- Failed to verify username / Invalid session: authentication. Launcher, Mojang, or
online-modebehind a proxy. - Took too long to log in: timeouts. Network, modpack or
read-timeout. - Unable to connect to world: Bedrock. UDP port, IP:port, console method.
On our plans these are the issues support handles on Discord around the clock, and the ports, the SRV subdomain and Geyser's port are configured when the server is created.