Network Troubleshooting

A connection can fail anywhere between the server and the client. You can narrow down the issue by breaking down testing into different layers; on the computer running auto-mcs, from another device on your LAN, and from outside the network.

What’s happening?	Start here:
Nobody can join, including you	Test the server itself
You can join, but another device on your network can’t	Test your local network
Local devices can join, but players over the internet can’t	Test the public connection
Minecraft shows an error when trying to connect	Common connection errors

For add-on services with separate ports, use the dedicated guides: Geyser, Simple Voice Chat, BlueMap, or remote access. They use the same diagnostic approach with different ports and protocols.

If you’re troubleshooting connecting to auto-mcs through Telepath, see Telepath networking and connectivity testing instead.

Common connection errors

The error on Minecraft’s screen is a clue, not a diagnosis. Match what you see, then follow the test that actually isolates it:

What’s happening?	What it usually means:	Start here:
Connection timed out / getsockopt	The client couldn’t complete a connection. Check whether the address, firewall, or public route is reachable	Test the server, then the public connection
Connection refused / getsockopt	The destination actively rejected the TCP connection, often because nothing is listening on that port	Check the active port and run a TCP test
Unknown host / Can’t resolve hostname	The address couldn’t be found, or it was entered incorrectly	Re-check the address; playit users can test DNS
No route to host / Network is unreachable	The client’s network doesn’t have a usable route to the destination	For a LAN address, test your local network. For a public address, test the public connection
Incompatible version / Outdated client/server	The network connection works, but Minecraft versions or editions differ	Ensure the client’s game version matches your server’s version
Failed to verify username / Invalid session	Minecraft authentication failed rather than the network port	Sign back into the Minecraft launcher and retry; check Mojang’s X account for status updates
Connection reset / Disconnected after joining	The initial connection may have succeeded, but then something closed it	Check the server Console, version compatibility, and add-ons

If your error doesn’t match the table, copy the complete message and search for its most specific phrase. If the server logs show an exception at the same time, take a look at Server Troubleshooting instead.

Testing the server

A good place to start is to narrow down as many variables as possible. An easy way to rule out bad server or add-on configurations is to create a new Vanilla server; start with something fresh and basic.

Tip

You can select Stock Vanilla from the instant templates to set this up for you. Be sure to disable the playit.gg integration for now in settings, or click “no” when prompted to set it up

If you no longer experience connection issues on a new Vanilla server, that means something in your original server’s configuration is the problem; take a look at the Server Troubleshooting guide to resolve that instead.

If you’re still having issues with a new Vanilla server, make sure your server is actually accepting connections. On the computer running auto-mcs, launch the Vanilla server and open Minecraft Java Edition, select Multiplayer → Direct Connection, and enter localhost:25565. If the port is different, replace 25565 with the server’s active port from the server info on the Launch screen.

Note

If auto-mcs is running in headless mode on a host without a desktop environment, you can use a tool like mineflayer to test logging in programmatically

Example of how to log in using mineflayer

On the Vanilla test server, set online-mode = false in the server.properties editor, and then restart the server

Next, create this login-test.js script:

const mineflayer = require('mineflayer')
const bot = mineflayer.createBot({
    host: process.argv[2],
    port: Number(process.argv[3] || 25565),
    username: 'TestBot',
    auth: 'offline'
})

bot.once('spawn', () => {
    console.log('Login successful!')
    bot.quit()
})

bot.on('error', console.error)
bot.on('kicked', console.error)

Finally, install node.js if needed, then install mineflayer and run the script:

npm install mineflayer
node login-test.js localhost 25565

You will see Login successful!, or an error

Did it work?

• Yes: The server is functional and accepting local connections. Continue by testing your local network.
• No: Make sure localhost is typed correctly, and open the server’s Network Settings to compare the port with the address you entered. On a fresh Vanilla server, this input should be empty and default to 25565. If the server is crashing or shows errors, go through Server Troubleshooting first. If the server starts with no errors, you may need to configure the host firewall.

Test your local network

Find the server’s LAN address

On the computer running auto-mcs, copy the LAN IP from the server info on the Launch screen; this is the address of this computer on your local network.

Otherwise:
Windows	Open Command Prompt, then run ipconfig. Look for IPv4 Address under the active Wi-Fi or Ethernet adapter
macOS	Open System Settings → Network, select the active Wi-Fi or Ethernet connection, and find its IP address
Linux	Open a terminal and run ip -4 addr. Find the address on the connected Wi-Fi or Ethernet interface

Tip

While the server is running, you can also run !info network in the Console to view the runtime network configuration. This shows the active address and port, private and public addresses, and any temporary port reassignment caused by a conflict.

If the Port value shows a change such as 25565 → 25566, use the second port for the current session

It will usually look like 192.168.x.x or 10.x.x.x. For the following examples, we’ll assume the computer’s LAN address is 192.168.1.50; be sure to use the address you found from this step in its place.

On a second computer connected to your home network, open Minecraft’s Direct Connection and enter that LAN address with the active port, for example 192.168.1.50:25565.

If the second computer connects: your LAN is working, continue to testing the public connection.

If it fails: Continue by checking the next steps below:

Can the computers see each other?

On the second computer, open Command Prompt or Terminal and ping the computer running auto-mcs using its LAN IP:

ping 192.168.1.50

A working test will show something like:

Reply from 192.168.1.50: bytes=32 time=2ms TTL=64

A failure may show Request timed out or Destination host unreachable.

• You get replies: these computers can see each other on your local network, continue to testing the Minecraft port.
• No replies: check the Wi-Fi and router settings in check whether your devices are isolated. Some firewalls ignore pings, so a failed ping doesn’t mean the server is unreachable

Check whether your devices are isolated

If both computers have internet access but can’t see each other locally, check what network each one is actually connected to.

1. Check the Wi-Fi names. Both devices should be on your regular home network, not Guest, Visitors, a hotspot, or a school/public network. Guest networks commonly block access to other devices
2. Check the addresses. Compare their local IPv4 addresses using ipconfig or the network settings above. If one is 192.168.1.x and the other is 192.168.50.x, they may be on separate networks
3. Look for client isolation. In your router settings, find the Wi-Fi/network settings and look for AP Isolation, Client Isolation, Wireless Isolation, or Guest Isolation. These settings will prevent devices on your network from talking to each other

Tip

The router’s management address is usually listed as Default Gateway in Windows or Linux, and Router in macOS network details. You can usually access this address from a web browser

If the Wi-Fi networks and settings are configured properly but connections still fail, continue to the port test.

Test the Minecraft port

A reachable computer can still block the server’s port. On the second computer, run the command for its operating system, replacing the example IP/port with the server’s:

Windows PowerShell	Test-NetConnection 192.168.1.50 -Port 25565
macOS / Linux terminal	nc -vz 192.168.1.50 25565

Note

These commands test TCP ports only; they won’t work for UDP services like Geyser or voice chat

On Windows, look for:

TcpTestSucceeded : True

On macOS/Linux, look for a succeeded or open connection message. A failed test will show TcpTestSucceeded : False, timed out, or Connection refused, depending on the platform.

• The TCP test succeeds, but players can’t join: the network path is working. Check the Minecraft version, and the server Console for login errors when a player attempts to join. Also, see Common connection errors.
• The TCP test fails: check the active port in auto-mcs again, then check the computer’s firewall settings.

Check the host firewall

If Minecraft works on its own computer but another device can’t connect, the host firewall may be denying incoming connections, or the client firewall may be denying outgoing connections. Don’t disable the entire firewall.

Note

Start by following the instructions for the computer running auto-mcs first. If it still doesn’t work, follow these instructions on the client as well

Windows

1. On the computer running auto-mcs, open Windows Security → Firewall & network protection.
2. Choose Allow an app through firewall. Look for the Java runtime used by auto-mcs, not only the auto-mcs executable.
3. Allow Java on your trusted Private network. If it isn’t listed, use Change settings → Allow another app to select the Java executable used by the server. To find it while the server is running, open Task Manager → Details, right-click its java.exe (or javaw.exe) process, and choose Open file location. If several Java processes exist, confirm the one launching your server. Administrator permission may be required.
4. Restart the server and repeat the TCP test from the second computer.

auto-mcs also attempts to add an inbound firewall rule for Java when launching a server. If the administrator prompt was declined, the Console may report that Java is blocked.

macOS

Open System Settings → Network → Firewall → Options. Check for a blocked Java runtime and allow incoming connections for the Java application used by the server. Additionally, ensure auto-mcs has access to your local network. This is required for both macOS clients and hosts

Linux

There may be different firewall workflows depending on your distribution. Additionally, be sure to use the exact port specified for your server. For example with Ubuntu-based systems, check whether ufw is enabled:

sudo ufw status

If it’s active and your server’s port isn’t allowed, enable it with:

sudo ufw allow 25565/tcp

Then, try the TCP test again. If you’re using a different firewall manager, check its rules instead. To undo this rule later, run sudo ufw delete allow 25565/tcp.

If the port test now succeeds: continue to Test the public connection. If it still fails: check that you’re using the correct LAN IP, the current port, and a server that is listening on that interface. Return to Test your local network if needed.

Test the public connection

If people on your LAN can join but players from the internet still can’t connect, the server and LAN configuration are fine; the issue is isolated to the public configuration.

Note

You’ll have to test this from outside your own network. Have someone on another network join, or use a second computer on a mobile hotspot. Testing your public IP from inside your own LAN can fail if your router doesn’t support NAT loopback

Check the address you shared

• Port forwarding: players need your public IP/domain and the forwarded Minecraft port. Addresses like 10.x.x.x, 192.168.x.x, 172.16.x.x–172.31.x.x are private and un-routable. Additionally, auto-mcs displays the public IP in the server info on the Launch screen when it can detect that port forwarding is configured correctly
• playit.gg: players need the tunnel address shown in the server info, not your public IP. Use the tests below first, then follow playit troubleshooting for agent, tunnel, and account issues

Additionally, you can use a tool like mcsrvstat.us to test the public server address:

• Shows the correct server: an external service reached the status endpoint. If a player still can’t join, check their version/edition and the connection error.
• Shows offline: the checker couldn’t obtain a status response, but that doesn’t prove joining is impossible. Try a real client on another network, then follow port forwarding checks or playit tunnel checks depending on how you expose the server.

Note

mcsrvstat.us caches responses for about five minutes. A server with enable-status=false may show offline even when players can join, so also test with a real Minecraft client.

If you’re port forwarding

1. Ensure your router’s port forwarding rules show the same port that’s in the server info, on the local address of the computer running auto-mcs. See WAN/internet configuration for more details
2. Make sure the destination LAN IP still matches the host. A DHCP address change can leave the forwarding rule pointing at the wrong computer. See static addressing for more details
3. In your router, find its WAN IP or Internet IP. On any computer, run curl api.ipify.com to retrieve your public IP address. If these addresses do not match, another network is translating the connection before it reaches your router

Note

If the WAN address itself is private, you may be behind another router or Carrier-Grade NAT (CGNAT). In this case, port forwarding won’t work. You may need to ask the network administrator or ISP whether they can provide a reachable public address, or use playit.gg instead

If the router rule is correct and LAN works: test again from a different network. If it still fails, ask the router/ISP administrator whether inbound connections or CGNAT prevent forwarding, or use playit.gg instead.

For the full LAN/WAN explanation, see Networking Overview.

If you’re using playit.gg

See the playit.gg troubleshooting guide instead