Plugin Conflict

If you've been sent to this page, you're having trouble with a plugin feature and a helper suspects it is caused by a Plugin Conflict.

This page documents what that is and what to do about it.

What is a Plugin Conflict?

A plugin conflict means that you have an issue in one plugin (eg, Citizens or Denizen or whatever else) but it is likely caused by some other plugin (unknown which, it could be any on your server).

This can happen when multiple plugins rely on the same basic Minecraft or Spigot features in a way that doesn't click together, or in some cases when an external plugin is making calls to the first plugin's API that shouldn't be happening (eg some plugin is telling Citizens to remove all villager NPCs without you knowing).

What do I do about it?

Step 1: Identify the fault

First, you have to find out what plugin is causing the problem.

In many cases, there's a clear linkage that you can use to make some guesses - eg, when Citizens is not able to control the scoreboard properly, if you're running a plugin that is intentionally controlling the scoreboard (eg to display text to players on it, or to have special effects on it, or whatever else), you can start by guessing that plugin is at fault and testing that.

Other times you don't have any guesses, and you need to find which plugin it is from the list of all plugins on your server.

When you have a suspected plugin, or you only have a few plugins that need to be tested, you can test 1-by-1: remove a suspected plugin, restart your server, and test the issue. If the issue is gone, that plugin was at fault.

If you have a lot of plugins to test, the best technique is a binary search: remove half of your plugins and test like that. If the issue is gone, the issue is in the half you removed. Otherwise, try without the other half. Once you know which half it's in, you can then try with half of that half (now a quarter of total plugins) removed, and repeat this strategy until you have just 1 plugin at fault.

In some cases, you may benefit from starting a secondary local test server - just launch a minimal Spigot server on your home PC and test locally. Start with just plugin having issues to see whether the issue still occurs. If it doesn't, start transferring plugins and configurations piece-by-piece from your actual server until it breaks again.

Step 2: Deal with the faulting plugin

If you've tried every test and even with a blank default server running just the at-issue plugin you still have the issue, you can come back and report that information. Ideally include a full copy of your log file on this test server to help us replicate the issue ourselves (so we can fix it).

If you've identified a specific plugin at fault,

• Tell us what plugin was at fault, and any other relevant information you may have gathered
• In some cases we may be able to just deal with it from there, other times we'll ask you to report the issue to the developer of the plugin at fault. In those cases, we encourage you to tell the relevant developer that you spoke with us and sent you there, and ideally report the issue on a public location (such as a Spigot forum topic, or a GitHub issues page) and link us to the public post you made, so we can work with that developer to solve the issue for you.

Addendum: Technical Note On Scoreboards

Scoreboard-related issues are the most common plugin conflict.

This can break: the "/npc name" command (toggles name visibility), the ability to have NPC names longer than 16 characters, the "/npc glowing" command, and of course the "/npc scoreboard" command.

The way NPC scoreboard functionality works in Citizens is simple: NPCs are added to dynamically generated teams, which are added to the main scoreboard (Bukkit.getScoreboardManager().getMainScoreboard()).

Many scoreboard plugins will change what scoreboard players view (Player#setScoreboard(...)). This change, importantly, hides the main scoreboard from the player. That means, changes to the main scoreboard do not get seen by the player. Which, in turn, means that scoreboard-related functionality in Citizens will seem to stop working.

There are two ways to correct this in a scoreboard plugin (both of these should be considered good practice in general). The first: copy all data from the main scoreboard to your secondary scoreboard (in an ideal world, Spigot would be doing this automatically - but at the moment that isn't the case). The second: send your custom scoreboard changes via NMS-driven packets instead of producing a secondary per-player scoreboard (this is also in consideration as a change to Citizens, as a way to workaround the frustratingly common scoreboard plugin conflicts).

Update: This was fixed in a recent Citizens version, by way of Citizens itself now managing scoreboard details through packets to prevent interference.