This is a comprehensive troubleshooting guide designed specifically for this plugin, although most of it involves basics of troubleshooting for any software.

You don't need to read and do all the steps below, but reading it definitely adds to your "general knowledge" as a server owner and can be extremely useful.

You can report bugs in the Spigot's Discussions, by joining the Discord server, or opening an issue on GitHub. Out of all these places, the Discord server is the most active of them all.

Before Reporting

Before reporting bugs, let's make sure about a few things.

• You're using Java 8 or 11 (16 for Minecraft 1.17+). Any Java version above Java 8 should work, but not necessarily.
• Make sure you're not in Admin Mode or have permissions (or op) that can bypass specific limits.
• You're using the latest server version of that minor update. For example, the plugin doesn't support 1.14, 1.14.1, 1.14.2 and 1.14.3 It only supports 1.14.4 which is the latest (patch) version of 1.14 minor version.
• Make sure you're using the latest dev-build which is accessible in the discord server. The version on the Spigot is also the latest dev-build most of the times. This might cause other instability issues.
• You're using Spigot or Paper. Other forks might cause issues.
• Check if other plugins are causing this issue (plugin conflicts). Read compatibility section for info on what's supported and what isn't. Specially if you're using server mods, which are not supported.
• Check if your issue is related to a broken/outdated config file.
• Some corrupted data errors automatically fix themselves after occurring once. They usually come with a message before the error. These issues can only be caused by manually modifying data files, force stopping the server or server crashes.
• Due to the nature of compilers design system, some plugin errors are actually made for server owners to understand them. Make sure to actually read the error message first. The useful messages are typically the first 2 messages in the whole error.
• Check the FAQ to see if your issue has been answered there.

Reporting

• Explain your issue, don't just leave the error unless you're sure that it's self-explanatory (which you cannot tell unless you're a Java developer.)
• Make sure to include the whole error, DO NOT cut the error. Some errors also have a message before them, make sure to include those as well when reporting. If you're not 100% sure, just paste the whole log file.
• When sending errors use Pastebin (or any other pasting service). Don't send screenshots or files (unless you're sending the whole log) or other pasting websites. (It's always better to post errors as plain text inside Discord, since Discord will automatically capture huge texts as a file format, and Discord also has a file viewer which is much better in terms of accessibility than using Pastebin.)
• Specify your server version and build. In most cases this is already in the error. It's not really necessary. (You can get that in /ver command)
• If something is not working without a console error, the reproduction steps from scratch are needed, not when it happens all of the sudden. I cannot help you if you don't provide reproduction steps.

Plugin Conflict

A plugin conflict means that two or more plugins are defining a set of behaviors that is not compatible with each other and this incompatibility can lead to different issues. In simpler words, it's when a plugin does something that breaks something else in another plugin.

Software conflicts are a general issue and can happen between different types of softwares. This conflict can happen between plugin-plugin, mod-mod and even plugin-mod (which is a highly probable conflict.) Most of the time this is not a bug and simply an incompatibility between the two plugins that the developers can choose to add support for.

Here are some examples regarding to kingdoms plugin specifically:

• Installing both kingdoms and another faction plugin will not work because kingdoms will not know which chunks are considered to be claimed by the other plugin and vice versa (the faction plugin doesn't know which lands are claimed by kingdoms) to prevent them from being claimed again.
• Installing a mob limiter/anti-lag plugin it's possible that it'll prevent kingdom guards/soldiers from spawning.
• Installing a chat plugin while having kingdoms global chat formatting enabled can result in duplicate chats.
• Mods and plugins inherently use different systems and they're bound to conflict at some point.

Identifying conflicting plugin

1. Remove all plugins except kingdoms to confirm that it's a plugin conflict.
2. Remove 50% of the plugins (except kingdoms of course)
   • If the issue is solved that means the problematic plugin is in that removed 50% so remove all plugins and put those 50% of the plugins that you removed then repeat step 2.
   • If the issue not solved, that means the problematic plugin is in the remaining 50% so repeat step 2 again.

Timings

If you're experiencing lag in your server, you need to get a timings report using spark plugin which is available on all platforms.

[!IMPORTANT] Spigot and Paper timings are no longer accepted. Please use spark instead.

Now, to start timings, you have to turn it on by using /spark profiler start --thread * command, then you'll have to wait at least 30 minutes for it to gather accurate information. Once the 30 minutes is done, get a report using /spark profiler open command. Now you'll get a link. Report that link to the developer.

[!NOTE] When getting timings report it's important to specify the --thread * option. This makes the profiler to monitor all of the server threads for potential issues in threads other than the main one, since KingdomsX takes advantage of Multithreading to improve the server's performance. While this itself will take more resources and increase the file size, it will give more information that can be used.

During the time you wait for timings to gather information, the best thing you can do and you should do is to continue doing what you might suspect to be the source of the lag. For example, if you're experiencing server lag when someone breaks a structure block, then keep placing and breaking structure blocks during that time.

Note that the only part of the plugin that is known to be laggy is turrets. The rest of the plugin is completely optimized using the latest techniques (unless it's a bug) If you increased your turret limit per land or changed their settings in Turrets folder unreasonably, I cannot help.
Also, FPS drops or high pings are not related to most plugins (at least not this one.)

[!TIP] Lag Spikes: This is a term that is used when your MSPT 95%ile is around an acceptable value (under 50ms), but your max MSTP is significantly higher (e.g. 100+ even as high as 3000) these are lags that occur from time to time that last for a short amount of time; hence the word spike; which is still noticeable to players, but for a very short amount of time. To track these kinds of spikes, you only need to monitor tasks that take longer than average. You can configure spark to do this by using /spark tickmonitor --threshold-tick <milliseconds> command where should be set to a value higher than 100.

[!TIP] flags.sh website has nothing to do with all this, but it's a nice Aikar's flags generator.

Reproduction Steps

Most errors are straight-forward for many developers, but sometimes there might be no errors at all or you might be asked to provide reproduction steps in order for a developer to help you. No, this doesn't mean that they want you to show them a step by step guide on how to fuck them. What this term means is that the developer of the plugin cannot make the error happen (reproduce) on their machine (usually a clean paper server installation with the latest version of the plugin and server software with no other plugin installed, unless specifically related to the error), so you have to give them reproduction steps which is short way of saying, "What do I (the developer) need to do to make this error happen?". Without this it's almost impossible for me to fix certain errors, because it can depend on various things such as your server software, version, conflicting plugins, configs, data and even OS.

---

Images

Images are sometimes useful, but if you send an image of your entire screen and expect someone to spot the issue, that's not going to work. You need to explain what the issue is when you send images. Use Windows Snip & Sketch tool which is the best screenshot tool you can get, and only capture the important parts, or even highlight small important details with the markers in the tool.

Videos

Videos are sometimes very helpful and sometimes it just makes things very confusing. For example, if you send a video showing issues related to small graphic details and your video's quality is too low, nobody can understand anything from it. Sending a video without explaining anything in plain text, like what the issue is and what you're doing (specially when you're pressing keyboard keys) isn't going to help. In fact, you should never send videos, make GIFs, that way you can capture a part if your screen with the best quality and lowest size, FPS isn't an issue in almost all reports. If you're going to send videos, please, make sure they're not larger than 50MB.

---

Explanation

You need to explain reproduction steps in detail. Specially when it involves other plugins. I as Minecraft plugin dev, have a basic general knowledge about most other popular plugins, but I can't remember all the details and I need to be sure.
For example if you tell me:

This happens when I right-clicked the item and my Nexus GUI opened.

Ignoring what "this" refers to, the first issue here is that a lot of context is missing. What item did you right-click exactly? How did this item have the ability to open the nexus GUI?
After rewording it a little, the reporter now says:

I'm using ChestCommands to open the nexus GUI.

But the question still remains. How can the item actually open the nexus GUI? Well, in this case, it's very obvious from the plugin's name. Any moron can guess that it opens "chests" (GUIs) with "commands" and the command that can open Nexus GUI remotely is /k nexus open, but developers don't like this kind of guessing game or start reading the entire plugin's description/wiki just to find this little piece of information. So, a complete useful sentence will be:

I use ChestCommands plugin which allows me to bind any command, such as /k nexus open to a certain item and it executes that command when I right-click that item. When I right-click that item, it opens my Nexus GUI, and that's where this issue happens.

---

Not all reproduction steps are useful. I need steps that actually contribute to the issue. For example, if you tell me:

/k nexus command doesn't open any GUI after dying, re-spawning and going to the server's spawn

and the actual issue being:

/k nexus command doesn't open any GUI after dying and re-spawning

the fact that "you went to the server's spawn" doesn't change anything. The issue still occurs if you don't go there, thus that doesn't contribute to the reproduction steps and is a waste of time for both people who reported it and people testing it.

This also includes situations when the developer asks you about a specific thing and only want an answer related to that specific thing. Having additional information isn't necessarily going to annoy the developer, it's just that it might be a waste of time, specially for you. This mostly happens with yes-no questions.

Data Corruption

Data corruption is a common issue not just with Kingdoms or Minecraft, but with a lot of other software.
Sometimes server owners don't properly shut down their servers by using the shut down button on their panel or using the standard /stop command. Or sometimes their server just crashes entirely due to some plugin, lack of resources, etc. Or sometimes they manually change data or important settings that can break things. This leads to a serious issue in which data isn't properly saved and synchronized. When someone force stops the server (by closing the terminal window or killing the process) or the server crashes, no plugin has any time to react to save itself. It's like shooting someone in the head and expecting them to do something about it. This isn't the matrix... Or is it?

Some of these issues include:

• Worlds being deleted or renamed. Kingdoms will get confused because it had data in a certain world, but now it cannot find it.
• Data fails to synchronize:
  • A kingdom thinks a player is their member, but the player data contradicts it, saying that they're not.
  • A kingdom thinks a land is claimed, but the land data contradicts it, saying that it doesn't belong to that kingdom.
  • A structure/turret is placed, but the block was broken and Kingdoms data wasn't saved, but the World data was. It leads to invisible structures.
• The data file itself was corrupted due to not having enough space, not completing the file write operation, other IO failures, etc.
• Data being changed manually in an attempt to fix an error to cause even more issues.
• Deleting certain settings that the existing data relies on. For example deleting a turret style config file while there are some turrets with that same style placed around the world.

[!TIP] Some of these issues can be avoided in case of a system failure if you use a proper database method like H2 (which is the default), but older versions of the plugin only had JSON, which couldn't properly deal with these issues.

[!IMPORTANT] While the plugin attempts to fix some of these issues automatically as it encounters them, it's better to fix them manually as soon as possible as they can cause other issues later on.

In order to fix these issues, a magical command was added called /k admin fsck.