If you followed our Minecraft server setup guide and something’s not quite right, you’re not alone — a handful of issues account for the vast majority of first-time Docker Minecraft server problems. Here’s how to diagnose and fix the most common ones.

Server Won’t Start

Check the logs first, always:

docker logs -f mc-server

This is the single most useful troubleshooting step — the logs almost always tell you exactly what went wrong.

Common causes:

• EULA not accepted. Make sure -e EULA=TRUE is included in your run command. Without it, the server refuses to start.
• Port already in use. If another process (or a previous container) is already using port 25565, the new container will fail to bind. Run docker ps to check for existing containers, and stop/remove old ones with docker stop mc-server and docker rm mc-server before starting a new one.
• Corrupted world data. If you interrupted a previous server ungracefully (like a hard shutdown mid-save), the world files in your data volume can become corrupted. Check the logs for chunk or NBT errors — if you find them, you may need to restore from a backup or start a fresh world.

Friends Can’t Connect (But It Works Locally)

This is the most common issue overall, and it’s almost always one of these:

1. Port forwarding isn’t set up correctly.

• Confirm you forwarded TCP port 25565 to your server machine’s local IP address in your router settings
• Double-check the local IP hasn’t changed — if your server machine doesn’t have a static local IP, DHCP can reassign it, breaking your forwarding rule silently

2. Firewall is blocking the connection.

• Check your OS-level firewall (Windows Defender Firewall, ufw on Linux, etc.) — it may be blocking inbound connections on port 25565 even though port forwarding is correctly configured at the router
• Temporarily disable the firewall to test (re-enable it afterward and add a proper rule instead of leaving it off)

3. Your ISP uses CGNAT (Carrier-Grade NAT).

• Some ISPs, especially on residential plans, place you behind CGNAT, meaning you don’t have a truly public IP address, and port forwarding won’t work no matter how correctly it’s configured
• Test this by checking whether your router’s WAN IP matches what a “what’s my IP” search shows from a device on your network — if they don’t match, you’re likely behind CGNAT
• If this is the case, you’ll need to contact your ISP about a public IP option, or use a tunneling service as a workaround

4. Wrong IP shared with friends.

• Make sure you’re sharing your public IP address (found via a “what’s my IP” search), not your local network IP (something like 192.168.x.x), which only works on your home network

Server Crashes or Freezes Under Load

Common causes:

• Insufficient RAM allocated. Check your MEMORY environment variable — if it’s set too low for your player count or world size, the server can crash or become unresponsive. Increase it if your machine has the headroom.
• View distance set too high. A high view-distance setting in server properties forces the server to load and render more chunks simultaneously, which is a common cause of lag and crashes on modest hardware. Try lowering it if you’re on a budget mini PC.
• Too many mods for available resources. Heavily modded servers need significantly more RAM and CPU than vanilla. If you’re running a large modpack on limited hardware, consider trimming mods or upgrading your machine.

World Not Saving Between Restarts

This almost always comes down to your Docker volume mapping.

• Confirm your -v flag correctly maps a real folder on your host machine to /data inside the container (e.g., -v /home/user/minecraft-data:/data)
• If you used an anonymous volume instead of a named one or a bind-mounted folder, your data may not be persisting the way you expect — check with docker volume ls to see what’s actually being used
• Never delete or recreate the container without first confirming your volume mapping is correct, or you risk losing world data

Server Running Old Minecraft Version After Update

If you expected the server to auto-update to a new Minecraft version and it didn’t:

• Check your VERSION environment variable — if it’s pinned to a specific version rather than set to LATEST, it won’t auto-update
• Pull the latest image with docker pull itzg/minecraft-server before recreating your container, since an outdated local image can also cause this

Container Keeps Restarting in a Loop

• Check logs immediately with docker logs mc-server — a crash loop almost always has a clear error message explaining why
• Common culprits: corrupted world data, incompatible mod combinations, or insufficient allocated memory causing repeated out-of-memory crashes

Still Stuck?

Most issues trace back to one of three places: port forwarding/networking, memory allocation, or volume mapping. Working through those three in order resolves the vast majority of problems. If you’re still stuck after checking all of the above, the container logs are almost always your best next step — they tend to spell out the exact cause more clearly than any general troubleshooting guide can predict.