Most Minecraft plugins store settings in YAML (.yml). A single tab character, missing quote, or bad indent can prevent the plugin from enabling — or worse, load defaults and silently wipe custom messages.
Validate the file before you restart. Line-and-column errors are faster to fix than guessing from a console stack trace.
Validate first — paste any plugin config into the free YAML Validator to catch syntax errors, then copy a clean UTF-8 dump.
Section 01
Why YAML breaks plugins
Bukkit/Paper configs are parsed with SnakeYAML (or similar). Invalid syntax usually means:
- The plugin fails to enable and prints a parse error with a line number.
- The plugin falls back to a default config and your edits appear “ignored”.
- Only part of the tree loads — nested keys under a broken parent never apply.
YAML is indentation-sensitive. Spaces and tabs are not interchangeable. Stick to two spaces per level in plugin configs unless the plugin docs say otherwise.
Section 02
Common mistakes
| Mistake | What to do |
|---|---|
| Tabs mixed with spaces | Replace tabs with spaces. Most editors can show whitespace and convert on save. |
Unquoted & / : in strings |
Wrap message strings in single quotes: '&aHello!'. Colour codes and MiniMessage tags often need quoting. |
| Duplicate keys | YAML keeps the last duplicate; earlier values silently disappear. Search for repeated keys after merges. |
| Broken lists | List items need a dash and consistent indent under the parent key. |
| Bad anchors / aliases | Resolve or remove &name / *name references if you are not intentionally reusing nodes. |
Example of a safe quoted message block:
messages:
welcome: '&aWelcome, {player}!'
reload: 'Config reloaded.'Section 03
Validate before you reload
- Copy the full contents of the plugin’s
config.yml(or other YAML file). - Paste into the YAML Validator.
- Fix any reported line and column — do not reload until it parses clean.
- Optionally reformat for a consistent 2-space dump (note: reformatting strips comments).
- Paste back into the server file, save as UTF-8, then reload the plugin or restart.
Keep a backup copy of working configs before large edits. A bad save plus an auto-regenerated default is a common way to lose custom messages.
Section 04
Safe edit workflow
- Edit offline when possible — validate, then upload.
- Change one section at a time on live servers so you can bisect failures.
- After reload, check console for the plugin’s enable line and any “using defaults” warnings.
- Test the feature that depends on the keys you changed (messages, menus, rewards), not only
/plugins.
FAQ
Frequently asked questions
Why did my plugin ignore my config edits?
Often the file failed to parse and the plugin loaded defaults, or a duplicate key overwrote your value. Validate the YAML and check console for parse errors on enable.
Should I use tabs or spaces in plugin YAML?
Use spaces only — typically two spaces per indent level. Mixing tabs and spaces is a frequent cause of SnakeYAML parse failures.
Does reformatting remove comments?
Yes. Pretty-printing YAML usually strips comments. Keep a commented master copy if you rely on inline notes.