Start by finding the boundary where the connection stops: the selected address, Paper's listener, the network filters, or Minecraft's login checks. An open SSH session and an active service do not establish that a player can join.
This guide covers an existing Minecraft Java / Paper server directly on Ubuntu 24.04, using minecraft.service and /srv/minecraft from the setup guide. Bedrock, a proxy such as Velocity, containers and modpack servers need their own traffic path. Run Linux commands on the VPS unless a step says otherwise; replace the example port if yours differs.
Record the failure before changing anything#
Ask the affected player for the exact error, the address entered, the client release and the time of the attempt. Establish whether everyone fails, one household fails, or a particular account fails. Change one thing per retry so a successful attempt tells you something.
| Observation | First investigation |
|---|---|
Connection refused | Listener, port and reject rules; the response may come from a firewall |
Connection timed out | Address, filtering and route; the message does not identify a particular firewall |
| Explicit incompatible-version, allowlist or account message | Game admission; the client has reached a responder |
| Friends join, but one player cannot | Compare that player's endpoint and network with a working attempt |
| Server list looks offline, but direct joining works | Status visibility rather than a general outage |
Confirm what is actually listening#
On the VPS:
sudo systemctl status minecraft --no-pager
sudo journalctl -u minecraft -n 100 --no-pager
sudo ss -ltnp 'sport = :25565'
Look for completed startup in the journal and the process owning the TCP socket. A restart loop is a startup problem. A different Java process on the expected port may be a second instance, so do not kill it until you identify its service and world.
ss can show both the address and process. A listener on 127.0.0.1 only accepts local connections. An IPv4 wildcard listener covers local IPv4 interfaces; an IPv6 listener needs an actual IPv4 test before you assume both families work.
Read the launch configuration and the relevant properties:
sudo systemctl cat minecraft
sudo sed -n -E '/^(server-ip|server-port|online-mode|white-list|enforce-whitelist|enable-status)=/p' /srv/minecraft/server.properties
Check that WorkingDirectory points to the instance you inspected. If the unit selects another config, inspect that file instead. In this direct-server setup, keep server-ip empty and align server-port with the client endpoint. Paper's troubleshooting reference identifies an incorrect binding address and an occupied port as possible startup failures.
If you correct properties, stop the service normally, retain a copy of the file, edit it and start again. Inspect the fresh journal and socket before asking players to retry; changing a file does not change an already running listener.
Check the endpoint and both firewalls#
Give friends the VPS's public IPv4 and actual port, for example PUBLIC_IP:25565. localhost, 127.0.0.1 and your home computer's private address do not name that VPS for a remote player. Compare a direct IPv4 attempt with the hostname: if only the hostname fails, inspect its DNS records rather than reinstalling Paper.
Java game connections use TCP; Query and remote administration are separate listeners. Inspect existing rules first:
sudo ufw status verbose
sudo ufw status numbered
If UFW is active and no applicable earlier deny rule blocks the traffic, add the missing game rule:
sudo ufw allow 25565/tcp
sudo ufw status numbered
The Ubuntu UFW guide explains rule inspection. Also check the provider's firewall/security group attached to this VPS: protocol, destination port and permitted source must match. A rule restricted to yesterday's player IP will fail after their network address changes.
Do not disable the firewall or open every port as a diagnostic shortcut. If UFW is inactive, this command stages a rule but does not enable filtering; locate the actual filter. Before separately enabling UFW, preserve your real SSH port and existing application rules, then verify a second SSH session.
Observe one external attempt#
On the affected player's Windows computer, test the same address in PowerShell, replacing PUBLIC_IP:
Test-NetConnection -ComputerName PUBLIC_IP -Port 25565
TcpTestSucceeded tests TCP reachability, not Minecraft login. A successful result sends you to game admission. A failed result still needs comparison with the server.
For a short capture, install the tool on the VPS if missing:
sudo apt update
sudo apt install -y tcpdump
sudo tcpdump -ni any 'tcp port 25565' -c 20
Ask the player to attempt a join while this runs. Stop with Ctrl+C if fewer packets arrive; -c 20 is a packet limit, not a timer. The upstream manual documents capture options. This command prints packet summaries without saving a payload file.
Compare timestamps and the player's current public source address. No matching packets points you toward the selected endpoint, upstream filters or client path; it does not prove which one is broken. Incoming attempts without a completed exchange require checking guest filtering, binding and the return path. Successful transport plus an explicit game rejection belongs to the login branch.
If other players work, try the affected player on another network, such as a mobile hotspot. That comparison narrows the investigation; it is not proof that a router reset or disabling antivirus will fix it.
Separate a home server from a VPS#
A home server needs a different path: public endpoint → home router forwarding → server's private address. Use the server's LAN address for a local test and a genuinely external network for the public test. Failure from inside the home to its own public endpoint can involve router hairpin behaviour even while remote friends connect.
Compare the router's WAN IPv4 with the public address reported externally. A mismatch can indicate upstream NAT, including a second router. RFC 6598 reserves 100.64.0.0/10 for shared address space. That range is a useful clue, but its absence does not rule out provider NAT. Ask the ISP whether inbound public IPv4 is available; a forwarding rule on your router cannot configure the ISP's router.
For a directly addressed VPS, adding a forwarding rule to a player's home router does not open the VPS. If you prefer keeping supported instances organised on your own infrastructure, Nexardo's VPS management panel is an administration option; enrolling the machine and creating managed instances are separate steps.
Resolve admission after transport works#
Match the player's Minecraft Java Edition version with the server's game version. Bedrock cannot join this Paper installation directly. If an account is rejected, preserve online-mode=true; sign back into the launcher and inspect the corresponding server error instead of bypassing authentication.
For an allowlist rejection, an existing operator can enter /whitelist add ExactPlayerName in game. Granting operator rights is not required to admit a player. Check intentional bans separately rather than removing all restrictions.
Paper's property reference also distinguishes status display from admission: enable-status=false can make the list look offline while direct joining remains possible. Do not infer a closed socket from the list icon alone.
Finish with the affected player entering the intended world. If they join but movement or block updates lag, use the lag investigation guide. For an unresolved connection, retain the attempt time, endpoint, client release, relevant journal lines, socket owner and rules. Remove player IPs and other private data before posting logs publicly.
