Troubleshooting

When something goes wrong, work from the evidence: read the log first, reproduce the problem, and change one thing at a time so you know which change fixed it. If your question is a how, where, or what rather than a fault to diagnose, the FAQ is the faster path.

Start with the logs

The server prints to the console as it runs, and writes the same output to a log file in your server folder:

• logs/latest.log - the current session.
• logs/<date>-<id>.log.gz - previous sessions, rotated and gzipped.

latest.log is the first thing to check when something misbehaves. See the configuration reference for the full folder layout.

The server won't start

endstone: command not found

The launcher isn't on your PATH. Re-check the method you installed with on Getting Started, or run it through the same tool you installed it with (for example uv tool run endstone).

Failed to bind to the port

An "address already in use" error means something else holds UDP 19132. Another Endstone or Bedrock server, or a previous instance that didn't shut down, is the usual cause. Stop the other process, or change server-port / server-portv6 in server.properties.

A newer Bedrock version is installed

Endstone refuses to start when the installed Bedrock build is newer than the release supports ("A newer version of Bedrock Dedicated Server is found"). Don't downgrade Bedrock by hand - update the Endstone package instead, as described in Updating your server.

The first-run download times out

On its first launch Endstone downloads Bedrock Dedicated Server, and to find the right download URL it first fetches a small data index from https://raw.githubusercontent.com/EndstoneMC/bedrock-server-data/v2. That host (raw.githubusercontent.com) isn't reliably reachable in every country - where it's throttled or blocked, the request can time out before the download even begins.

Point the launcher at a mirror of that data with --remote (-r):

endstone --remote <mirror-base-url>

Use a mirror you trust - the community can point you at a current one. See the CLI arguments reference for the default URL and how the option works.

Players can't connect

• Make sure UDP 19132 (and 19133 for IPv6) is forwarded through your router and allowed through the firewall.
• If players need Xbox sign-in to join, confirm online-mode is set as you intend.
• On a LAN, check that enable-lan-visibility is on.
• Connecting to a server on the same machine? Enter 127.0.0.1 as the address, not localhost - the Bedrock client doesn't resolve localhost.

"Outdated client!" or "Outdated server!" when joining

Bedrock only lets a client join a server running the exact same Minecraft version, and the disconnect message tells you which side is behind:

• Outdated client! - the player's game is older than the server. They need to update Minecraft to the version your Endstone release pins.
• Outdated server! - the server is older than the player's game, usually right after Minecraft auto-updated on their device. Update the server so it matches; until you do, players on the newer version can't join.

The fix is to get both sides onto the same version. If you need clients on different versions to connect at once, that's what Endweave is for - see Updating your server.

A plugin won't load

First, check you have the right file for your operating system. Native plugins are platform-specific: .dll on Windows, .so on Linux. A .dll dropped on a Linux server (or a .so on Windows) is simply ignored - it isn't the right extension for the platform, so the server never tries to load it and prints no error. Re-download the build that matches your OS - see Adding plugins.

If the file is correct but the plugin still doesn't come up, watch the console at startup for the load error. Common causes: a native plugin built against a different Endstone version, or a Python plugin built for a different Endstone or Python version.

The server is lagging

Most of a server's load scales with how much world each player sees and how many players are online. There's no single correct value for the settings below - find the bottleneck by watching CPU and memory under your actual player count, then pull the biggest levers first, restarting after each change so you know what helped. All of these live in server.properties.

Check the hardware first

Microsoft's baseline for Bedrock Dedicated Server is a 64-bit Intel or AMD machine with at least 2 cores and 1 GB of RAM - a floor for a handful of players. More players, a larger view distance, and busier worlds all want more cores and memory. If the box is already maxed out, no setting will fix it.

Lower the view distance

view-distance (default 32, minimum 6) is the single biggest lever. It's the radius of chunks, in each direction, the server sends to every player - and the cost multiplies with player count. Dropping it from 32 to 8-16 is the most effective change you can make on a busy server.

Lower the tick distance

tick-distance (default 4, range 4-12) is how far out the world is actively simulated - mobs, redstone, crops, and entities. Raising it spreads simulation over more chunks per player, which costs CPU. Keep it low unless a feature you run needs entities ticking farther out.

Cap players and threads

max-players (default 10) caps concurrent connections - every online player adds chunk, entity, and networking work, so set it to what your hardware can actually carry rather than an aspirational number. max-threads (default 8) caps the server's worker threads; 0 lets it use as many as it can, which is usually right on a dedicated box. Lower it only when sharing a host with other services.

Tune networking

• compression-algorithm (zlib or snappy) and compression-threshold (default 1 byte) trade CPU against bandwidth. snappy compresses faster but less tightly than zlib. compression-threshold is the smallest packet that gets compressed, so raising it compresses fewer packets - less CPU, more bandwidth - while lowering it compresses more, spending CPU to save bandwidth. On a CPU-bound server, raise it.
• client-side-chunk-generation-enabled offloads terrain generation to clients, lowering server-side cost. Endstone keeps it off by default so the world seed stays hidden - with it on, the seed is sent to clients, revealing where ores and structures are - so turning it on trades that privacy for performance.

A balanced starting point

For a small community server on modest hardware, these values are a reasonable baseline to tune from:

view-distance=12
tick-distance=4
max-players=10
max-threads=8

Raise view-distance if the server has CPU and RAM to spare; lower it first if you see lag as players spread out.

The server crashed

If the server crashes, Endstone prints the crash details to the console and saves a report to:

crash_reports/crash-<timestamp>-server.txt

It also sends anonymized crash data upstream so the developers can find and fix the cause. When you report a crash, attach the crash_reports/... file along with logs/latest.log - together they're usually enough to pin down what happened.

Getting help

If you've read the log and you're still stuck, the community can help. Before asking, gather the evidence so others don't have to guess:

• logs/latest.log (and any crash_reports/... file if the server crashed).
• The Endstone and Bedrock versions from endstone --version and the startup banner.
• What you changed last, and the exact steps to reproduce.

Then reach out on the Endstone Discord or open an issue on GitHub. For quick how / where / what questions, check the FAQ first.