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, I'll outline some of the best ways to make it accessible throughout this article.

Use a test server

If you're running a Minecraft server, you should always have a test version of it available. Not just for determining the cause for issues, but for testing plugin and version changes. I recommend to do the following with a test server, to prevent any interruptions to your players.

Is it caused by a plugin?

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 step when troubleshooting server problems, is to test the server without any plugins installed. If the problem no longer occurs, you now know that a plugin causes it. If it still happens, you should report it to Paper or Spigot.

Finding the Problem Plugin

If 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.

What to do with the Problem Plugin

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 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's likely that plugin is not the cause. 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 plugin's name.

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.

Other ways to find 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 with the final say and is generally the issue. In the case where nothing shows up, vanilla spawn protection could be the cause.

Conclusion

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 understand the basics 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!

About the Author

Maddy Miller

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.