Join our Discord and be part of our community!

Troubleshooting your Minecraft Server

This guide explains how to troubleshoot performance and network issues on your Minecraft server. You will learn to identify whether lag is caused by server performance (TPS) or connection problems (latency), and how to resolve them using tools like Spark and MTR.

Prerequisites

Before starting, ensure you have:

• Access to the server console
• Ability to upload files
• Downloaded the Spark plugin/mod

Performance vs. Network issues

Assuming that the server is actually able to start and that there’s no underlying configuration problem that would prevent it from starting up / accepting connections, the problems that you may encounter will either be performance or network based.

Performance problems indicate that the server is not able to process everything it has to for players to play smoothly, which will thus be noticeable during gameplay as all players will start experiencing issues.

Networking issues differ from performance problems as it doesn’t necessarily mean that something is wrong with the server itself, rather the connection to the server which can have various causes; also meaning that it doesn’t necessarily affect everyone.

To start diagnosing the problem, the first step is to actually determine whether the problem is due performance or networking.

Finding the cause

Download the correct version of Spark for your server (e.g., Bukkit for Paper/Purpur).

To install and check server health:

• Upload the Spark .jar file to the plugins/ (or mods/) folder.
• Restart the server.
• Run /spark tps in the console.

Check the output:

• Healthy: TPS is 20.0 and tick durations are below 50.0.
• Performance Issue: TPS is low or tick durations are high. Go to Performance Issues.
• Network Issue: TPS is normal but lag persists. Go to Network Issues.

Performance issues

To diagnose the cause:

• Run /spark profiler start --timeout 300.
• Wait for the profile to complete.
• Open the link provided.

Below is an example report. Spark indicates the server is suffering from performance issues as the TPS is below 20.0.

Scroll down to the section titled “All View” where you want to ensure that the Label is set to Time per tick.

By expanding the selection, we can see that Minecraft’s main tick() function is taking 108.07ms on average, whereas it should be below 50.0ms to reach a stable 20.0 TPS.

The diagnosis process will now consist of going further down this tree to find what is taking up a long time to process, where this report can be attributed to the following:

• ServerChunkCache.tick()
• EntityTickList.forEach()

The report indicates that spawning mobs is the largest cause of lag as far as this function is concerned, as indicated by NaturalSpawner.spawnForChunk().

To resolve this, you would either have to reduce the simulation-distance setting in the server.properties file so that each player simulates less chunks around them, thus ensuring that the server does not need to try spawning in monsters in as many chunks.

Alternatively, you may modify the bukkit.yml configuration file to either reduce the maximum amount of mobs that can spawn in a given chunk, so for example reducing monsters to 35 in the spawn-limits section.

Further optimizations can be made here by increasing the ticks in between each spawn event, in other words increasing the delay it takes for the server to try spawning in new entities, which is controlled by the ticks-per section. A value of 1 would mean that the server tries spawning in new mobs every 0.05 seconds which is rather unnecessary, increasing the value to 10 would increase that delay to 0.5 seconds, making it substantially easier for the server to process while still being unnoticeable to players in practice.

Networking issues

If Spark shows healthy performance, the issue is likely network-related.

To diagnose:

• Generate an MTR report.
• Analyze the report using Linode’s guide.

This MTR shows an extremely unstable ping as shown by the difference between the Worst column. Since the ping was varying a lot during the first few hops, this can be attributed to an outage with the Internet Service Provider, something which we as the hosting provider cannot resolve.

In the following MTR report, it can be noted that not all packets that were sent arrived at the destination, indicated by the fact that 1 389 were sent in the first hop and 2 388 made it through to the end.

Since this loss can be seen in the % row on the cogentco upstream, this means it is an issue with the hosting provider, in other words us. In this particular example the loss is extremely minor and can be attributed to the fact the MTR is being taken from the other side of the planet to the physical server.

In some cases, the problem may be solved by enabling a VPN such as Warp that Cloudflare provides for free, as they may alter the route that packets take, bypassing problems that your internet service provider’s default routes could have.

If you require further assistance, you can open a support ticket here.

Feedback and suggestions can be submitted here or further discussed on our Discord server.

• Troubleshooting your Minecraft Server
• Prerequisites
• Performance vs. Network issues
• Finding the cause
• Performance issues
• Networking issues