Handling an Out of Memory error
Minecraft Java Edition can run into an error state called "Out of Memory" or "OoM" when there are either insufficient resources for the JRE to manage the RAM used by the server or the server itself doesn't have enough remaining RAM to store additional data. There can be a few reasons for this, ranging between there being an insufficient total amount of RAM allocated to your server, there being inefficient CPU time to manage the RAM usage of your server, and there being insufficient RAM available to the JRE itself.
Out of memory errors are often caused by the following situations:
Not enough RAM for the JRE
The JRE runs alongside the server and manages the interface between the server software and the OS. Modern Minecraft versions have become more reliant on the optimizations that the JRE can provide, and that makes the JRE more reliant on server resources like RAM and CPU time.
If the server software itself uses all of the allocated RAM before the JRE can clear it, then the JRE will slow down and end up unable to keep up with the server software. You can prevent this by adjusting the Max Ram Percentage to leave more ram for the JRE.
Not enough CPU for the JRE
The JRE runs alongside the server and manages the interface between the server software and the OS. Modern Minecraft versions have become more reliant on the optimizations that the JRE can provide, and that makes the JRE more reliant on server resources like RAM and CPU time.
If your server is overloaded then the JRE may have difficulty keeping up with it's task of clearing the unused RAM. You can try to optimize your server to reduce the CPU usage or make the JRE more efficient at clearing the unused RAM by using flags like Aikar's Flags.
Not enough RAM for the server
It may be as simple as your server not having enough RAM to store the data it needs.
As a general rule, your server will use all of the RAM it has allocated and only clear it when there's a need to store new data. That's why making sure you have enough RAM and CPU time available for the JRE is important. But that can only go so far, and the amount needed for your server can be affected by te following:
- Player count
- Each player on the server will need to have the chunks and entities in their area loaded into RAM.
- Mods/Plugins
- Not just quantity of Mods/Plugins, but the complexity of the Mods/Plugins themselves plays a large part.
- Age of your world
- As your world increases in complexity, it'll take more RAM to store the data. This is especially true for modded worlds.
- Server Settings
- Settings/features like View/Render Distance, Simulation Distance, Spawn Rates, Chunk Loading, and Entity Count can be a major factor in the amount of RAM needed to run your server.
- Playstyle
- The way you change the world can have a massive effect on your server's performance. How you handle entities and block updates in farms, as well as how you store items effects how the server can manage the data stored in RAM. In general, the more technical a playstyle, the more intensive it'll be on the server and the more careful you'll have to be to maintain performance.
- Be careful replacing vanilla features with plugins/mods, as they may take more resources than the feature you're trying to replace!
If you've tried adjust the above and you're still experiencing OoM errors, then you may need to upgrade your server.
General Memory Leak
Sometimes the server will "leak" memory. That happens when data is added to RAM and is never "released", or allowed to be deleted after it's no longer needed. This can be an issue with the Vanilla server itself, the 3rd party server software you're using (Forge/Paper/Fabric), or with a Mod/Plugin you've added.
If the leak is slow, you can mitigate it by having a regularly scheduled server restart.
If it reaches the point that your server crashes more often than 24 hours, you may want to try the following troubleshooting steps.
Using a test server for troubleshooting is ideal!
You can run a test server by downloading your server files like you would for a Manual Backup and starting the .jar file that's named in your server's Server Jar File Startup Parameter using the command line.
- Remove known chunk loaders
- Some mods and Vanilla after 1.21.2 have the ability to load chunks when there aren't any players nearby. It can be easier to troubleshoot where the memory leak is coming from if you disable chunk loading.
How you disable it can vary.
- Some mods and Vanilla after 1.21.2 have the ability to load chunks when there aren't any players nearby. It can be easier to troubleshoot where the memory leak is coming from if you disable chunk loading.
- Watch for any players that join before a memory leak starts.
- Sometimes the leak is associated with a specific player or area of the world. So taking not of when the server crashes and when was online and where between crashes/restarts is a good place to start.
- Test with a fresh world.
- This is especially common in modded situations where blocks/entities themselves tend to store a lot of data.
- Use a Linear/Binary Search on your Mods/Plugins/Datapacks to see if any of them are causing it.
- It's very common for a Mod/Plugin/Datapack to mishandle it's data and cause a leak. It's difficult to identify though, so it's best to just brute force it by performing a Linear/Binary Search until you identify the culprit.
Server Uptime
Under ideal conditions your server should be able to clear out any un-needed data from RAM when it needs space to store more, but the longer a program is running the more likely it is for small amounts of mis-marked data to accumulate. This may not be a typical "leak" where it's a relatively large amount of data coming from one source, but instead just general data that wasn't or can't be cleared correctly.
The easiest way to combat this is to give your server a regular restart using a restart schedule.