Having memory issues with your spigot, paper, or other Minecraft server software? Your in the right place!
Unlike many languages, Java, which is what your server runs on, manages and collects memory by itself! This makes life Much easier for developers, but can be a little confusing for you, the server owner.
Java is an object oriented programming language, which means that every bit of code is an object that's stored in memory. When your not longer using an object, such as an entity on your server dies and no plugins are referencing it, Javas Garbage Collector will delete it, freeing up memory.
This is all great, but the Garbage Collector does take some resources to run, so Java only bothers running it when it needs to, or when memory is running low. This means if you give it Java 8Gb of Ram, it will use almost all of that space before cleaning up. That is why you may think your server needs more memory because it's using all you gave it!
Another thing to keep in mind is that Java keeps most objects in a space of memory called the Heap.
This is where the Garbage Collector will clean up, and you can define the heap size using the
-Xms and -Xmx values in your startup arguments.
-Xms: This value is the minimum amount of allocated RAM, and this is what Java allocates to
the Heap the instant your server starts.
-Xmx: This value is the maximum amount of allocated RAM, and the Heap can never go over
this size, because the Garbage Collector will cleanup before.
It's strongly recommended to set both those values to be the same for Minecraft, because it takes effort to ask the OS to allocate more, so we might as well just do all that at startup
You may be confused right now because your Server Panel claims that your server is using more RAM
than you set your -Xmx value to. This happens because the Heap isn't the only memory Java uses.
Java stores some other things outside the heap, often called Off-Heap, Overhead, or Stack.
This space is for other Java stuff, and for Minecraft it generally accounts for 1.5-2Gb of additional RAM.
This Off-Heap memory may even be larger than you main heap!
Java Heap vs Stack Explained
If your using the server panel Pterodactyl, or your host uses a Docker-Based System, it's important
to leave space for that Off-Heap, or else your server could crash due to an out of memory error.
Remember, setting the -Xmx only defines the Heap size, and if you set your containers limit to
the same, there will be no more room for the off-heap, and your server will crash.
It's very important to set your -Xmx to 1.5-2Gb Lower than your container limit.
If your not already using them, use them. Very skilled people have created the most optimized set of arguments for Minecraft, that will reduce your resource usage significantly. This page tells you what flags to use, and provides a very in depth explanation of what each one does. Aikars Flags
Your server panel is most likely reporting the allocated RAM to you, not the actual heap size.
This will make it appear that your memory is steadily increasing, when really it's just allocating more
ofer time because Java will never "un-allocate" RAM.
Many plugins such as Sparks /spark healthreport or Essentials /lag can accuratly report
the heap size. If you watch this frequently, you will notice that it fluctuates a lot.
This is because the Heap will increase as objects are created, then once it gets full the
Garbage Collector will clean up all the old objects and the size will go back down!
Spark Spigot Plugin
Chances are you came across this page when you thought you had a memory leak, and if you still think that's the case even after reading everything here and on Aikars Page, your going to have to take a Heap Dump to find out.
A Heap Dump is a file that contains a list of every single object in your heap, so you can later analyze them with tools such as Eclipse Memory Analyzer. Eclipse Memory Analyzer
You can take a heap dump on Paper with /paper dump, and if you have Spark you
can use /spark heapsummary, although a real heap dump is better.
Eclipse FAQ, May Come In Handy
Memory leaks happen when the Garbage Collector is unable to clean up some object that are no longer in use, causing heap size to increase. This is generally down to misbehaving plugin that is not de-referencing unused objects.
The Garbage Collector only removes objects that are no longer being referenced, meaning that there is no path from the start, or the server instance, to that object. Java Garbage Collector In Depth
Overtime, your Heap size average is bound to increase, because every plugin has a few tiny memory leaks, and together they add up. To combat this, it's highly recommended to have your System Automatically Restart every few days, to start with a fresh heap and keep everything running smoothly. The only time this would be a real problem is if the increase was substantial, causing your server to run out of memory within 24-48 Hours.
You may have heard the old rule "1 gb per 10 players" but this is completely false. There really is no way of knowing how much RAM you will need, so you just have to try. Giving your server more RAM than it needs is often doing more harm than good, because its making Garbage Collector cycles more resource intensive.
A good starting point is usually around 3Gb, and if the TPS is steady and everything seems good try to run it like that for a few days, and if there's no problems you could try reducing that down by 100Mb. Just repeat this process until you get to the point where it seems the servers starting to struggle, and you can give it some back.
Make sure each of the increments experiences average or peak player counts before deciding it's enough, and you can start at diffrent points depending on what type of server it is, such as a well optimized lobby server may only need 1gb or less!
If you disable the Config option keep-spawn-chunks-loaded in your paper.yml you can even get your heap size to 0.5Gb or less! By default Minecraft keeps a few chunks around your world spawn loaded for faster joining, but if players aren't always going to join at the world spawn, this is completely pointless.
This isn't entirely in the scope of this topic, but a great tutorial for Paper users on optimizing your server is linked. Paper Config Optimizations
Thanks for reading through this whole page, and I hope you now have a decent understanding of how your server and Java in general operates, and you can solve all your memory related problems!
Im certainly not an expert, and if I got anything wrong in this please let me know! Also, I would love for you to add a Star to this to give me motivation to write more of these things in the future. Thanks!