How to debug unknown Minecraft server plugin issues

Posted on December 08, 2019 in minecraft

Tagged with: minecraft servers, tutorial
How to debug unknown Minecraft server plugin issues

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.

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

Finding the Problem Plugin

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.

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 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"

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 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!

Check out these popular related posts!

How to actually use Paper/Spigot Timings and understand the limitations

Posted on November 30, 2019

A common tool for finding lag on Minecraft servers moment is Timings. But there is more than meets the eye when it comes to Timings report, and they're not always able to tell you what is causing lag.

The Ultimate Guide to Running a Minecraft Server

Posted on September 17, 2020

Running a Minecraft Server can be a daunting task. In this article you'll find answers to questions, guides for various systems, and advice on server administration.

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.