The /reload command has been around in Bukkit since the early days of Minecraft multiplayer. However, the command is generally seen amongst the community as broken and unsafe.
Why does it exist?
The goal was to allow server owners to reload configuration files of plugins and the server itself quickly and easily. However, to make it easier on plugin developers, the command ended up having a fatal flaw that made it unsafe to use. This decision was unlike earlier server platforms like hMod, which behaved in a much more controlled manner. The Bukkit team decided that the reload command should disable every plugin, and then try to enable them again. Essentially simulating the server shutting down and starting up again while it’s still running.
Why is it broken and unsafe?
As Java doesn't provide a supported or safe way to unload or reload code that is already loaded, this started to cause a few subtle issues and errors. Loading everything again in some cases caused conflicts between the old code and the new code from the reload. This issue is especially severe when replacing plugin jar files. Due to this, both Spigot and Paper have never recommended the use of the reload command. Significant distaste for the reload command due to the issues it caused was already evident as early as 2011, only shortly after Bukkit had started. Since then, these issues have gotten significantly worse.
As Minecraft evolved, what needed reloading became a lot more complicated, until the concept of reloading became utterly infeasible. Every recent update has seen the reload command cause further issues. Right now, no one should ever use the /reload command under any circumstance. It causes significant instabilities within Minecraft, Bukkit, Spigot, Paper and almost any plugin that uses the Bukkit API. Currently, an action as simple as checking player permissions can cause issues after a reload. If a plugin errors after a reload, it's (likely) not the plugin's fault, but instead a symptom of the fundamentally broken reload command. Unlike the early days of 2011, plugins can’t just make changes to better support the reload command.
Since the move to more modern version of Java, this problem has gotten substantially worse. The way the command and the internals of Java work have become even less compatible with each other, potentially causing entirely unsolvable errors. A common one is the "zip file closed" error that’s started popping up on many Minecraft server support forums in the recent years.
So what should be used instead?
When adding new plugins, updating an existing plugin, or removing a plugin, you should always restart the server. Reloading can and will leave your server in an unstable state. When making changes to a plugin’s configuration however, most plugins provide a command to reload its configuration. For example, /cb reload will reload CraftBook’s configuration files. These commands don’t suffer the same issues as the /reload command. If a plugin doesn’t have one of these commands, ask them to add one or just restart your server.
If you've replaced any jar files, reloading the server will create issues, even if you don't notice it. The /reload command is always unsafe and error prone.
Hotswapping as a developer
If you’re a developer and using /reload to test your plugins faster, this is also a bad idea. Making code changes frequently and reloading will substantially exacerbate the problem. Instead, you can safely use a code hotswapper such as the IntelliJ debugger to safely apply code changes from your IDE directly to a running server. This is both more convenient than building and reloading, and substantially safer.
A common belief is that for a development environment like this it’s fine, because it’s not going to impact a production server. However, due to the types of issues that reloading can cause, you can end up impacting the behaviour of the plugins you’re testing. Given the whole point of a development server is to test changes, using a command that can alter the behaviour entirely defeats the point of doing it. If you’re a developer working on a plugin, use the hotswap method as above, and if you’re a server admin adding plugins then restart the server. Developer environments do not mean that using /reload is safe, it’s just as dangerous as using it on a production server just for different reasons.
What about PlugMan?
Using plugins such as PlugMan to enable or disable plugins is still problematic. It not only hits the same issues as above, but it also breaks expectations that plugins have about the server. As Bukkit is not designed for plugins to load by themselves, this can cause issues where plugins are in an invalid state. Not only that, it's common for plugins to assume the server has just started when the plugin loads, so the plugin may be working with incorrect data if started later on.
What about other platforms like Sponge, or vanilla Minecraft?
This warning doesn't apply to Sponge's reload command. The Sponge reload command does not do what Bukkit does, and instead sends an event to plugins telling them a reload was requested. It is then the plugin's responsibility to reload configurations.
The vanilla Minecraft reload command for datapacks is also safe. If you want to use the Minecraft /reload command to reload datapacks on Bukkit-based servers, you can safely use /minecraft:reload.
This article is part of a series on how to run a Minecraft server. Click here to check out more!
About the Author
Hi, I'm Maddy Miller, a Senior Software Engineer at Clipchamp at Microsoft. In my spare time I love writing articles, and I also develop the Minecraft mods WorldEdit, WorldGuard, and CraftBook. My opinions are my own and do not represent those of my employer in any capacity. Find out more.