Short answer
Work top to bottom: confirm the server is running and has finished starting, retype the address exactly, check the Minecraft version matches on both ends, read the exact error, and only then look at the network. Most refused connections are a stopped or sleeping server, a typo, or a version mismatch.
Every failed join looks the same from the player's chair, whether the cause is a typo or a blocked port, so the fixes have to be tried in an order. Take the order from likelihood, not from what you know about networks. Checking the version before the server is online is backwards; checking the firewall before the address is wasted.
This guide is that order, five checks that between them cover nearly every refused connection. It works whether the server runs on PufferHost or on your own machine, with one extra step for self-hosted servers.
Before you start
- The exact server address the player is using
- The exact error text or screenshot
- Panel access to see whether the server is running
1. Confirm the server is running and has finished starting
Open the panel. Is the server running? A stopped server refuses every connection until it starts, and a server that is still generating its first world refuses until the console prints Done (X.XXXs)! For help, type "help".
On PufferHost, free servers go to sleep after five minutes with nobody online and wake when the first player joins. The very first join after a break can time out once while the server wakes. Wait for the panel to show it online and have the player try a second time before going any further.
[12:31:04 INFO]: Done (6.402s)! For help, type "help"2. Retype the address, and copy it rather than retype it
Delete the saved server entry and add it again from the address shown in the panel, character by character. No http://, no spaces, and the port appended only if yours is not 25565. Chat apps hide characters and autocorrect inserts them, so a message saying "the address is pufferhost dot com" is not an address.
If the player can copy and paste it directly and it works, the fix is done: replace their saved entry with the copy rather than the version they typed.
3. Check that the Minecraft versions match
Vanilla, Paper and Purpur servers run exactly one Minecraft version and reject clients on any other. Check the version the panel shows for the server and the version in the player's launcher.
The error tells you which side is behind: "Outdated server. Please use 1.21.11" means the player must update their client; "Outdated client. Please use 1.21.11" means the server does. Changing the server version covers the second case, and it applies to Paper and Purpur as well as vanilla.
/version4. Read the error, because each one names its fix
"You are not white-listed" means add them to the whitelist (how). "You are banned" states the reason and when it ends. "Failed to verify username" or "invalid session" means their launcher session is stale: fully quit the launcher, reopen it and join again. "Outdated client" you have already seen.
If one player fails while others are on, the problem is on their end, not the server. Have them try a well-known public server. If that works, your server's access lists are the next place to look; if it does not, it is their client or network.
[12:33:10 INFO]: UUID of player SomePlayer is this, possibly an attempt to impersonate?
[12:33:12 INFO]: Disconnecting SomePlayer: You are not white-listed on this server!5. Test the network from a different one
Only now suspect the network. Have the player join from a phone hotspot. If it works on mobile data, their router, school or work network is blocking Minecraft's traffic, and nothing about the server is wrong. Some antivirus software blocks the game the same way.
For a self-hosted server the same test points at the server's own network: port 25565 must be forwarded from the router to the machine, the machine's firewall must allow the Java process, and the host must not be behind carrier-grade NAT. Port forwarding has the router steps, and the ports reference explains why the port has to be open at all.
Good to know
- "Connection timed out" and "connection refused" are different symptoms. Timed out means the packets went nowhere, which is a blocked network or an offline server. Refused means something answered and said no, which is a running server rejecting this specific connection: wrong address, wrong port, wrong version or an access list.
- A server that appears grey in the multiplayer list with no icon, and never progresses to connecting, is failing before the game even tries: asleep, wrong address, or a network block, in that order.
- Screenshots settle most of this. The exact wording of the error picks the fix, and a paraphrase picks a guessing game.
Common questions
Why does it say connection refused when the server is clearly online?
The server is running but rejecting that one connection. The usual causes are a stale address from before a migration, a wrong port, a version mismatch, or an access list. Read the console at the moment the player tried to join: rejections are logged with the reason.
Can my firewall or network block Minecraft?
Yes. School and work networks and some antivirus products block the game's traffic. Joining from a phone hotspot is the fastest test: if it works there, the fix is on the network, not on the server.
The server pings grey and never connects. What is wrong?
A grey ping means no handshake reached the server at all. In likelihood order: the server is asleep or stopped, the address is wrong, or the player's network blocks the connection. Start or wake the server, retype the address from the panel, and test from another network.
One friend cannot join but everyone else can. Whose problem is it?
Theirs. Their version, their launcher session or their network. Ask them to update to the server's version, quit the launcher completely and reopen it, and try a different network. If a public server also fails for them, it is conclusively their setup.
Sources
Official documentation this guide was checked against.
Rather not run this on your own machine? PufferHost gives every player a free Minecraft server with 3 GB of RAM and 10 slots. Create a free server.