🩺 ConfigDoctor: Find the Broken Config Line in Seconds
ConfigDoctor scans the YAML configs of every installed plugin and explains mistakes in plain language — with the exact file and line number — instead of a 40-line stack trace.
Instead of decoding SnakeYAML errors, read one line: file, line, what is wrong.
It is built around one rule: zero false positives on healthy configs. If ConfigDoctor says something is wrong, something is wrong.
🎯 Why Your Server Needs This Plugin
Real line numbers. Every report points at the exact file and line — no "somewhere inside this 900-line config".
Universal detection. It does not need to know a plugin's schema: your server's own registries, sibling-value analysis, real file checks — it works on configs of any plugin.
Everything in chat. All problems are printed, grouped by file, sorted by line — no "… and 12 more".
Bug reports included. Every scan is saved to a report file you can paste straight to a plugin's author.
💡 How It Works
- Drop the jar into
plugins/ and restart the server.
- Run
/configdoctor scan — the scan runs off the main thread and never blocks the server.
- Read the chat output, grouped by file and sorted by line.
- Open the saved report in
plugins/ConfigDoctor/reports/ (keeps the last 10) to paste into a bug report.
Run it after every plugin update or manual config edit — it takes a few seconds.
🖥️ How It Looks
--------- ConfigDoctor ---------
Scanned 17 files, skipped 0, broken 0
1 error(s), 1 warning(s)
ShieldStun/config.yml - 1 problem(s):
ERROR line 26
'sounds.block.name: b1212' - not a valid sound key
-> use a vanilla key like block.note\_block.pling
ShulkerNest/config.yml - 1 problem(s):
WARNING line 22
'radii.1: ф' - this value is text, but the other values in this section are numbers
-> use a number here, like the others: 10, 15, 20, 25
Bug report saved: plugins/ConfigDoctor/reports/report\_2026-11-14.txt
🧪 Syntax & Minecraft names
Names are checked against your server's own registries — vanilla and whatever your version really has.
| Check |
What it catches |
| Broken YAML |
Tabs in indentation, bad indentation, unclosed quotes — with the exact line number |
| Duplicate keys |
The same key defined twice in one section |
| Unknown item names |
GOLDEM\_SWORD → did you mean GOLDEN\_SWORD |
| Unknown sound keys |
entity.zomby.growl → did you mean entity.zombie.growl (legacy names like LEVEL\_UP supported) |
| Unknown enchantments |
SHARPNES → did you mean SHARPNESS (legacy DAMAGE\_ALL supported) |
| Unknown potion effects |
Effect names that do not exist in your version |
| Broken hex colors |
&#GGGGGG → use &#RRGGBB |
🔢 Numbers & types
| Check |
What it catches |
| Negative prices and costs |
price: -5 |
| Text where a number belongs |
view-distance: abc, cooldown-ticks: да |
| The odd one out |
radii.1: ф among "2: 10, 3: 15" — sibling analysis, works in any plugin's config |
| Impossible chances |
chance: 150 — wrong on every scale plugins use (0–100 or 0–1) |
| Unknown time units |
delay: 10x → try 10s / 10m / 10h / 10t (ticks) |
| Impossible slots |
slot: 100 — no inventory slot exists above 53 |
🔗 References
| Check |
What it catches |
| Broken file references |
gui: menu.yml when the file does not exist in the plugin folder |
| Absolute Windows paths |
C:\\Users\\Admin\\menu.yml never works on a server |
| Link typos |
htps://example.com → did you mean https:// |
| Unloaded world names |
world: myworld when no such world is loaded (skipped if the plugin creates worlds itself) |
| Duplicate list items |
worlds: \[nether, nether\] |
💬 Messages, encoding & plugin.yml
| Check |
What it catches |
| Invisible characters |
Non-breaking and zero-width spaces, BOM, smart quotes in keys — the classic "copied from Discord and nothing works" |
| Broken encoding |
Files that are not valid UTF-8 (U+FFFD) — your Russian text will look broken in-game |
| Unclosed placeholders |
%player\_name without the closing % |
| MiniMessage tag typos |
<reed> → <red>, <grey> → <gray>, <underline> → <underlined> |
| plugin.yml mistakes |
Missing name / version / main, no api-version, broken permission defaults (default: ops), typos in known keys: commandes: → did you mean commands: |
| Empty values |
A key with nothing after the colon — the plugin will read null |
⌨️ Commands (permission: configdoctor.admin)
/configdoctor scan — scan every installed plugin's configs
/configdoctor report — path of the last saved report
/configdoctor reload — reload the ConfigDoctor config
Aliases: cdoc, cdoctor. The permission defaults to operators.
⚙️ Technical Advantages for Administrators
Performance: the scan runs off the main thread, directory listings are cached — nothing ticks in the background, nothing blocks the server.
Safety: strictly read-only. ConfigDoctor never writes to other plugins' configs — all output goes to its own reports folder.
Precision: issues are grouped by file and sorted by line, and the chat shows every problem (no truncation) so nothing is missed in a long scan.
Universality: no schemas required — registry checks, sibling analysis and real files on disk cover any plugin's config.
Configurability: every single check has its own on/off switch in plugins/ConfigDoctor/config.yml, and folders can be excluded with ignore-paths.
Compatibility: Paper, Purpur, Pufferfish or any Paper fork, 1.21.x up to the latest version (built and tested on 26.3). Java 21. No dependencies.
⚠️ What ConfigDoctor can NOT do
Honesty section, because this matters:
- It does not know other plugins' schemas. If
radius: 99999 parses fine and is a number, it cannot tell the value is absurd — the meaning of a value is known only to the plugin's author.
- It cannot check required fields of arbitrary plugins — a deleted
gui: section in an unknown plugin's config will not be reported.
- It cannot verify plugin-specific names (custom kit names, custom items) or whether a PlaceholderAPI placeholder actually exists on your server.
- It cannot check the inside of referenced files — a menu.yml that exists but is broken inside is another file's scan.
ConfigDoctor catches what can be proven wrong: broken syntax, names that do not exist in Minecraft's registries, values of the wrong type, and references that point nowhere. That is exactly the class of mistakes admins make most often when editing configs by hand.
📦 Perfect For
Admins who hand-edit configs between plugin updates.
Owners who copy configs from wikis, Discord and other servers.
Server-pack builders validating dozens of plugins at once.
Developers sanity-checking their own plugin's configs before release.
Install ConfigDoctor and never decode a SnakeYAML stack trace by hand again!
Chat, requests to add checks, false-positive reports, bugs, creating plugins for your needs — discord
Support the author: donate