YAML without tears: editing plugin configs

Nearly every plugin stores its settings in a .yml file — that's YAML, a format built to be human-readable. It mostly is, until one stray space or tab stops your whole plugin from loading. The good news: YAML has only a few rules, the console tells you exactly where you broke one, and the File Manager warns you before you even save. Learn this once and you'll never fear a config again.

The rules that matter

YAML is key: value, grouped by indentation. Ninety percent of config trouble comes down to five rules:

1. Indent with spaces, never tabs. This is the big one. A single tab character breaks YAML instantly, and you can't see the difference on screen. Use two spaces per level, consistently.
2. Indentation must line up. Items at the same level need the same number of leading spaces. Nesting means more spaces than the line above.
3. A space after every colon. enabled: true, not enabled:true.
4. Quote values with special characters. If a value contains a colon, #, %, &, or starts with a symbol, wrap it in quotes: motd: "Welcome: come on in!". Color codes are the classic trap — write prefix: "&aServer &7» ", quoted.
5. Lists use a dash and a space. Each item on its own line:

   worlds:
     - world
     - world_nether

Here's a small, correct config so the shape is clear:

settings:
  enabled: true
  max-homes: 3
  welcome-message: "&aWelcome, %player%!"
  disabled-worlds:
    - creative
    - minigames

⚠️ Heads up: Never press Tab to indent in a config file. It looks the same as spaces but YAML rejects it. If your editor inserts tabs on Tab, type the spaces manually.

Let the File Manager help you

You don't have to spot mistakes with your eyes. Open the config in the File Manager editor and it does real work for you:

• It's the VS Code editor engine (Monaco) — it shows line numbers down the left, which is exactly what the error messages reference.
• Set the language selector to YAML so it colour-codes keys, values, and strings — a value that isn't the colour you expect is a clue it needs quoting.
• Turn on word wrap (Alt+Z) so long lines don't hide off-screen, and use find & replace (Ctrl+H) to change a value everywhere at once.
• Best of all: the editor warns you if you try to save a file with syntax errors. That warning is your first line of defence — don't dismiss it and save anyway. See The File Manager.

💡 Tip: Copy the file before a big edit (multi-select → Copy in the File Manager). If your change breaks something, you've got the working version to fall back to.

Reading the error the console prints

Save a broken config, restart, and the plugin's loader (SnakeYAML) prints something like this:

[ERROR] Could not load 'plugins/Essentials/config.yml'
mapping values are not allowed here
 in 'reader', line 8, column 15:
    motd: Welcome: to my server
              ^

Read it like a map:

• line 8, column 15 — the exact spot. Jump to line 8 in the File Manager (the line numbers match), and count to column 15.
• The ^ pointer sits under the character that broke parsing. Here it's the second colon in Welcome: to my server — YAML thought a new key was starting. The fix is to quote the value: motd: "Welcome: to my server".

Two other errors you'll meet:

Full walkthrough of the position pointer for JSON and YAML: Config file syntax errors.

The safe editing habit

1. Copy the file first (or take a backup before a big change).
2. Edit in the File Manager with the language set to YAML.
3. Don't save past the syntax-error warning — fix it first.
4. Restart (or use the plugin's reload command) and watch the console for a clean load.
5. If it broke, the console names the line — go fix that one spot, or paste your copy back.

🎯 Good to know: A plugin that fails to read its config often either regenerates a fresh default (losing your changes) or disables itself. Either way the console says so — so always check the console after a config edit.

Verify it works

After a restart, the console should show the plugin enabling normally with no YAML error, and your changed setting should take effect in-game. Run /plugins — a plugin that loaded cleanly shows green.

Troubleshooting

• Plugin loaded but ignored my change — you edited the wrong file, didn't restart/reload, or the value needs quotes. Recheck the exact key and restart.
• Config reset to defaults — the file had a syntax error, so the plugin rewrote a clean one. Get your version back from your copy or a backup, fix the error, save.
• Console error names a line you didn't touch — a bad edit can shift how everything below it parses. Start at the line the ^ points to; the real mistake is at or just above it.
• Can't find the tab — turn on the YAML language mode and word wrap; misaligned colouring reveals it. Retype the whole line's indentation with spaces.

Next steps

• The File Manager
• Config file syntax errors
• Diagnosing plugin conflicts
• Backups