Setting up a Minecraft 1.20.4 server on Debian 12 (Bookworm) requires addressing Java version compatibility and port forwarding, as the default repositories often lack the specific JDK versions needed for modern Minecraft servers. This guide resolves common startup failures, permission errors, and connectivity issues by focusing on proper package installation, systemd service configuration, and network verification using modern diagnostic tools.
Java Version Compatibility
Minecraft 1.20.4 generally requires Java 17 or higher. Debian 12 ships with OpenJDK 17 by default, but older tutorials may suggest installing Java 8 or 11, which will cause the server to fail immediately. To verify your installed Java version, run:
java -version
If you do not have Java 17 installed, install it using the package manager:
sudo apt update
sudo apt install openjdk-17-jre-headless
Some users encounter issues because the
java command points to an incorrect version or is missing entirely. Ensure that the
JAVA_HOME environment variable is set correctly if you are running custom scripts. For most standard setups, the system-wide installation via
apt is sufficient and preferred over manual downloads from Oracle or Adoptium, as it integrates better with Debian’s security updates.
Server Directory and Permissions
Running a Minecraft server as the root user is a significant security risk and can lead to unexpected behavior. Create a dedicated user for the server process. First, create the user without a home directory requirement for login:
sudo adduser --system --no-create-home --group minecraft
Next, create a directory for the server files and assign ownership to this new user:
sudo mkdir /opt/minecraft
sudo chown minecraft:minecraft /opt/minecraft
cd /opt/minecraft
Download the official Minecraft server JAR file. You can fetch the latest 1.20.4 build directly from Mojang’s official link. After downloading, accept the EULA by editing the
eula.txt file:
echo "eula=true" > eula.txt
Failure to set the EULA to true will prevent the server from starting. Additionally, ensure that the
minecraft user has read and write permissions to the
/opt/minecraft directory. Incorrect permissions are a leading cause of "Permission Denied" errors during startup.
Systemd Service Configuration
Managing the server manually via SSH sessions is inefficient. A systemd service ensures the server restarts automatically after crashes or reboots. Create a service file at
/etc/systemd/system/minecraft.service:
[Unit]
Description=Minecraft Server
After=network.target
[Service]
User=minecraft
Group=minecraft
WorkingDirectory=/opt/minecraft
ExecStart=/usr/bin/java -Xmx1024M -Xms512M -jar server.jar nogui
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
Adjust the
-Xmx and
-Xms flags based on your mini PC’s available RAM. Over-allocating memory can cause the system to swap heavily, degrading performance. Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable --now minecraft
Check the status with
systemctl status minecraft. If the service fails, check the logs with
journalctl -u minecraft -e for specific error messages. This approach isolates the server process from user session issues, providing a more stable environment.
Network Connectivity and Port Forwarding
For players to connect, port 25565 must be open on your router and accessible from the internet. On the Debian host, verify that the server is listening on the correct port using
ss, which is the modern replacement for the deprecated
netstat:
ss -tlnp | grep java
You should see output indicating that Java is listening on
:25565. If nothing appears, the server may not have started correctly, or a firewall is blocking the connection. Check the UFW firewall status:
sudo ufw status
If UFW is active, allow the Minecraft port:
sudo ufw allow 25565/tcp
Many mini PCs operate behind CGNAT (Carrier-Grade NAT), especially if connected via mobile hotspots or certain ISP configurations. In these cases, standard port forwarding is impossible. If you cannot access your public IP, consider using a tunneling service like Tailscale or Ngrok, which allows secure remote access without exposing ports directly. Note that configuring WireGuard for local network access is distinct from internet-facing port forwarding; for detailed guidance on securing local connections, refer to our article on
Minecraft Server: Unable to Use IP Address for WireGuard Connection.
Troubleshooting Common Errors
If the server starts but clients cannot connect, verify your external IP address matches what you entered in the game client. Use a site like
whatismyipaddress.com to confirm your public IP. If you are using IPv6, ensure your router supports dual-stack routing, as some older Minecraft clients struggle with pure IPv6 connections.
Another common issue is insufficient disk space. Mini PCs often have smaller SSDs. Monitor disk usage with
df -h. If the drive is full, the server will crash or refuse to save world data. Clean up old backups or log files regularly.
Finally, ensure that your mini PC’s power settings are configured for high performance rather than power saving. Debian’s default CPU governor may throttle performance under load, causing lag spikes. You can check the current governor with
cpupower frequency-info and set it to
performance if necessary.
Frequently Asked Questions
Why does my Minecraft server crash immediately after starting?
Most immediate crashes are due to an incorrect Java version or an unsigned EULA. Verify you are using Java 17+ and that
eula.txt contains
eula=true. Check the
logs/latest.log file for the exact error code.
Can I run multiple Minecraft servers on one mini PC?
Yes, but each instance requires its own directory, port, and systemd service unit. Ensure you allocate enough RAM to each instance so they do not compete for resources, causing OOM (Out of Memory) kills.
How do I fix "Connection Refused" errors from clients?
This usually indicates a firewall block or incorrect port forwarding. Use
ss -tlnp to confirm the server is listening on 25565. Then, verify your router forwards external traffic on port 25565 to your mini PC’s local IP address.
Is it safe to run the server as root?
No. Running as root exposes your entire system to vulnerabilities if the server software is compromised. Always use a dedicated, non-privileged user account like
minecraft to isolate the application.
What if I am behind CGNAT and cannot forward ports?
Use a peer-to-peer tunneling solution like Tailscale. Install Tailscale on your mini PC and client devices, then connect using the Tailscale IP address instead of your public IP. This bypasses the need for router configuration entirely.