This is a comprehensive troubleshooting guide designed specifically for this plugin, although much of it covers basic 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 Spigot's Discussions, on the Discord server, or by opening an issue on GitHub. The Discord server is the most active of these options.

Before Reporting

Before reporting a bug, check the following points.

• 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 for that minor update. For example, the plugin doesn't support 1.14, 1.14.1, 1.14.2, or 1.14.3. It only supports 1.14.4, which is the latest patch of the 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 whether other plugins are causing the issue. Read the compatibility section for information about what is and is not supported, especially 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 design of the compilers system, some plugin errors are written for server owners to understand. Read the error message first. The useful information is typically in the first 2 messages of the full error.
• Check the FAQ to see if your issue has been answered there.

Reporting

• Explain your issue. Do not provide only the error unless you're sure that it is self-explanatory, which you cannot determine 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 stops working without a console error, provide reproduction steps that begin from scratch, not only what happened immediately before the issue. I cannot help you without reproduction steps.

Plugin Conflict

A plugin conflict occurs when two or more plugins define behaviors that are incompatible with each other. This incompatibility can cause different issues. Put simply, one plugin does something that breaks a feature in another plugin.

Software conflicts are a general issue and can occur between different types of software. They can occur between two plugins, two mods, or a plugin and a mod, which is especially likely. Most of the time, this is not a bug. It is simply an incompatibility that the developers may choose to support.

Here are some examples specific to the Kingdoms plugin:

• 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.
• A mob limiter/anti-lag plugin might 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 is not solved, 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.

Start the profiler with the /spark profiler start --thread * command, then wait at least 30 minutes for it to gather accurate information. After 30 minutes, create a report with /spark profiler open. This gives you a link that you can send to the developer.

[!NOTE] When creating a timings report, it is important to specify the --thread * option. This makes the profiler monitor all server threads for potential issues outside the main thread because KingdomsX uses Multithreading to improve server performance. This takes more resources and increases the file size, but it provides more useful information.

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 term applies when your MSPT 95%ile is acceptable (under 50ms) but your max MSTP is significantly higher, such as 100 or even 3000. These periods of lag occur occasionally and last only a short time, which is why they are called spikes. Players can still notice them. To track these spikes, you only need to monitor tasks that take longer than average. Configure spark to do this with the /spark tickmonitor --threshold-tick <milliseconds> command, where should be higher than 100.

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

Heap Dumps

A heap dump is a great way to analyze memory leaks that might be caused by the plugin. However, heap dumps produce extremely large files. You can create a full heap dump with /spark heapdump. Make sure to choose no compression.

Thankfully there are ways to significantly compress heap dumps. If you want to get a general idea of what your memory is being used on, you can use /spark heapsummary, but this is not useful in most cases.
The best zipping program that's currently known to compress them is the free 7zip program. You should compress your heap dumps with the settings highlighted in red as shown in the screenshot.
When done correctly, this can, for example, compress an 8GB file to 800MB.

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.
• A kingdoms/server error occurring which can potentially save your data in a bad format and you ignoring.
• 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.

To fix these issues, a magical command called /k admin fsck was added.