How to debug unknown Minecraft server plugin issues
Posted on December 08, 2019 in minecraft
A common issue Minecraft server admins face is unexplainable behaviour of which they can't find the cause. These issues may be harder to reproduce, not cause any errors, and not point to any particular plugins. While these issues are harder to find the cause of, throughout this article, I'll outline some of the best ways to make it easy.
As a disclaimer, I strongly recommend creating a copy of your server on a local machine for this process. Doing this allows you to make more extensive changes without disrupting players.
The first thing you should check for when trying to find troublesome issues is to test the server without any plugins installed. In the case that the problem no longer occurs, you now know that a plugin causes it. If it does, you should report it to Paper or Spigot.
In the case that a plugin causes the issue, you'll want to narrow down which plugin is causing it. One standard method for doing this is to remove half of your plugins and testing to see if it still occurs. If it does, remove another half. Continue doing this until the issue no longer occurs. Once it has stopped, you'll know that one of the plugins in the last group you removed is the culprit.
Once you've got this smaller group of narrowed-down plugins, you can use a similar strategy on this. Re-add half of them back, and continue until it starts again. You now have a smaller group of plugins. Keep doing this until you've narrowed it down to a single plugin. This concept is known as a binary search.
So you've found the problem plugin. Sadly you haven't yet verified that this plugin is the actual cause, but instead confirmed that removing it fixes the issue. There are many cases where another plugin can cause a problem, but only in the circumstance that another exists.
While potentially confusing, many plugins enable or disable certain features depending on whether or not you have another plugin installed. If the plugin you've narrowed down is something like ProtocolLib, WorldGuard, WorldEdit, or other commonly depended-on plugins, it is very likely to be an issue with a downstream plugin. One way to confirm this is to remove every plugin except for the problem plugin. If the issue no longer occurs, a plugin that depends on this one is the issue.
Finding which of your plugins is the actual cause, in this case, can be a fair bit harder. If you're using Linux and have zip/unzip installed, you can run the following in the plugins folder, with PLUGIN_NAME replaced with the name of the plugin.
for file in *.jar; do if ( unzip -c "$file" | grep -q "PLUGIN_NAME"); then echo "$file" fi done
If that fails, try the binary search again. This time, however, don't remove the plugin you narrowed down initially. The new plugin you narrow it down to is most likely the actual plugin causing the issue. To verify, try removing only that plugin from your server and trying to reproduce the problem.
If you have the plugin WorldGuard installed, you can use that to find a few common problems. In cases where block breaking, block placing, block interacting, or entity damaging are not working, WorldGuard has debug commands to find the cause. These commands, outlined on the documentation, tell you every plugin that interacts with events. The first plugin listed in the output of this is the plugin that had the final say and is generally the issue. In the case where nothing shows up, vanilla spawn protection could be the cause.
Overall, finding the cause of troublesome issues can be difficult. There are so many moving parts that interact with each other, that pinpointing the exact problem takes effort. The best thing you can do to ensure you're able to find issues quickly is to have a basic understanding of how plugins work, and what the plugins you have installed do.
Once you've found the issue, try reading up on the plugin's documentation or asking the developers. Removing a plugin should only be for worst-case scenarios where you're unable to get it resolved.
This article is part of a series on how to run a Minecraft server. Click here to check out more!
Share this with others!
Posted on January 04, 2020
Fabric came about after Minecraft Forge hadn't updated for Minecraft 1.13. Now that is has, is Fabric still relevant and worth using? What about Minecraft Forge?
Posted on May 09, 2020
Using WorldEdit with blocks added by mods on versions of Minecraft before 1.13 can be confusing, but there are a few ways to make it simple
A Decade of Survival Multiplayer. Celebrating the first 10 years of the Minecraft Multiplayer Community
Posted on August 04, 2020
As of today, Minecraft has had multiplayer for a decade. We have created a comprehensive history of the multiplayer community.