Fabric Minecraft server: Debian setup and troubleshooting

Introduction

CPU, memory and disk configuration of the Debian server

This article records the problems I ran into setting up a Minecraft Fabric server on Debian: server environment setup, Fabric mod compatibility, client connections, performance tuning and crash investigation.

The goal was not a large commercial multiplayer server, but a small survival environment for 3-5 people that also keeps:

  • lightweight Fabric mod support
  • low server cost
  • stable operation
  • support for client-side optimisation mods
  • as little setup work for friends as possible

Along the way I hit Fabric Loader version conflicts, Java version problems, client mod synchronisation, chunk loading speed and Watchdog crashes.

1. The server's basic environment

1.1 Hardware

The final server configuration:

Item Value
CPU 2 cores
Memory 8GB
System Debian 12 Bookworm
Java Temurin JDK 21
Minecraft version 1.20.1
Server Fabric Server
Network 6 Mbps bandwidth
Players 3-5

The server started as:

  • 2 cores, 4GB RAM
  • Java 17
  • Fabric 1.20.1

I later upgraded to 8GB of memory mainly for:

  • more room for mods
  • less memory pressure while chunks generate
  • better stability with several players online at once

2. System environment

2.1 Why Debian 12

I chose Debian 12 for the server rather than Ubuntu.
Main reasons:

  • lower system resource usage
  • fewer background services
  • better stability
  • better suited to a server that runs for a long time

Base environment:

Debian 12 (for stability)
Java 21
screen
Fabric Server

Cloud server instances and their resource configurations

Do not forget to open the ports


3. Installing the Fabric server

3.1 The initial Fabric Loader problem

The first server start gave:

Incompatible mods found!

Error:

Fabric API 0.92.8+1.20.1 requires Fabric Loader >=0.16.10

ModernFix requires Fabric Loader >=0.16.10

Cause:

The server was using:

fabric-loader-0.15.11

but the optimisation mod I installed required:

Fabric Loader >=0.16.10

Fix:

Download the Fabric server again:

wget -O fabric-server.jar \
"https://meta.fabricmc.net/v2/versions/loader/1.20.1/0.16.10/1.0.1/server/jar"

Upgrade Fabric Loader to:

0.16.10

4. Java version compatibility

4.1 Java 17 caused a failed start

After upgrading Fabric I got:

UnsupportedClassVersionError

class file version 65.0

What the error means:

class version 65 = Java 21
class version 61 = Java 17

Explanation:

Some components were already compiled for Java 21, but the server was still running Java 17.


4.2 Installing Java 21

The Debian repositories do not have:

apt install openjdk-21-jdk

so I used Temurin JDK:

Install directory:

/opt/java/jdk-21.0.11+10

Configuration:

update-alternatives \
--install /usr/bin/java java \
/opt/java/jdk-21.0.11+10/bin/java 2100

Verification:

java -version

The server's final runtime environment:

Java 21

5. Tuning the server start parameters

Final launch:

java \
-Xms2800M \
-Xmx2800M \
-XX:+UseZGC \
-XX:+ZGenerational \
-XX:+AlwaysPreTouch \
-XX:+DisableExplicitGC \
-XX:+PerfDisableSharedMem \
-jar fabric-server.jar nogui

What the parameters do:

ZGC

to reduce GC pauses:

-XX:+UseZGC

Good for:

  • many mods
  • long uptimes
  • large maps

a fixed heap

 
-Xms2800M
-Xmx2800M
 

avoiding the stutter that comes from resizing the heap at runtime.


6. Mods currently installed on the server

Server-side mods

The main ones right now:

Mod Purpose
Fabric API Fabric base API
Lithium game logic optimisation
ModernFix memory and startup optimisation
FerriteCore lower memory usage
Krypton network optimisation
Right Click Harvest right-click harvesting
EasyAuth login authentication

7. Client-side mods

On the client I additionally installed:

performance

Mod Purpose
Sodium large FPS gains
Iris shader support
Indium Sodium compatibility
Entity Culling fewer invisible entities rendered
Dynamic Lights dynamic lights

extended view distance

I also tried:

Distant Horizons

for:

  • LOD distant rendering
  • seeing terrain far beyond the normal view distance

But I found that:

when the server has not pre-generated the map:

  • distant areas show as blank
  • cliffs appear
  • the minimap goes black in places

Cause:

Distant Horizons can only render data the client already has.

It cannot invent chunks the server never sent.


8. Analysing chunk loading

8.1 Why you see cliffs

Minecraft's chunk loading flow:

Player moves
 ↓
Client requests a chunk
 ↓
Server generates or loads the chunk
 ↓
Sent to the client
 ↓
Client renders it

So:

in areas nobody has explored:

the server has no chunk data.

Distant Horizons cannot show real terrain.


8.2 Is 6 Mbps enough?

For 3-5 players:
6 Mbps is basically enough.
Slow chunk loading is mainly not a bandwidth problem; it is:

  • the CPU generating chunks
  • disk reads
  • Minecraft's single-threaded limit

9. Investigating server crashes

9.1 The Watchdog problem

The server had been crashing.

The main reason:

Minecraft's Watchdog detected:

Main thread unresponsive for too long

triggering:

Server force-closed

Common causes:

  • lots of new chunks being generated
  • players exploring quickly
  • mods occupying the main thread
  • GC pauses

10. Server performance testing

Using:

/spark tps

to run the test.

Final results:

TPS:

20.0 20.0 20.0 20.0 20.0

Notes:

the server holds full TPS.

Tick:

5.6 / 6.8 / 10.7 / 20.7 ms

Minecraft's standard is:

50ms = the limit

the current peak:

20.7ms

which is within the normal range.


CPU:

system 7%
process 6%

That means:

CPU pressure is very low.


11. Current state of the server

Environment:

Minecraft 1.20.1

Fabric Loader 0.16.10

Java 21

2 cores, 8GB

Fabric optimisation mods

Sodium client optimisation

Iris shaders

Distant Horizons LOD

Performance:

TPS: 20

MSPT:
<30ms

CPU:
low usage

Memory:
plenty

Current bottleneck:
not the server's performance.
The main issues:

  1. the world has not been pre-generated
  2. Distant Horizons does not have enough LOD data
  3. Minecraft's default chunk generation is the limit

12. What to optimise next

12.1 Pre-generate the map with Chunky

Recommended:

Chunky

Pre-generate:

For example:

Spawn radius: 512 chunks

Workflow:

Nobody online
↓
Server generates the map
↓
Region files are saved
↓
Players join and read them directly

noticeably improves:

  • stutter while exploring
  • broken terrain
  • Distant Horizons rendering

12.2 Adding gameplay mods

Since the client pack has already gone out, I do not recommend adding many mods that the client must install.

Prefer:

things that run server-side:

  • economy
  • quests
  • admin tools
  • world optimisation

to keep maintenance cheap for my friends.


Summary

Setting up this Fabric Minecraft server mainly solved a few core problems:

  1. matching Fabric Loader against mod versions
  2. Java 17 versus Java 21 compatibility
  3. syncing client and server mods
  4. investigating Watchdog crashes
  5. chunk loading and distant rendering
  6. performance testing and tuning

In the end the server reached a stable running state.

For a survival server of 3-5 players the current setup is enough; the next round of work should shift from “more hardware” to:

  • pre-generating the map
  • mod selection
  • world management
  • tuning for long-term stability

The main limit on a small Fabric server like this is usually not memory, but Minecraft's main-thread capacity and the pressure of world generation.

Related posts

Comments

Loading comments…

Music