YAML without tears: editing plugin configs

Intermediate 233 5 min read

Almost every plugin config is a YAML file, and almost every "my plugin broke" is one wrong space. Learn the handful of rules, how to read the error the console prints, and how the File Manager warns you before you even save.

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.

At a glance
You need	A plugin installed (so it has a config), and the File Manager
Plan	Any
Time	Ten minutes, then it's a reflex

The rules that matter

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

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.
Indentation must line up. Items at the same level need the same number of leading spaces. Nesting means more spaces than the line above.
A space after every colon. enabled: true, not enabled:true.
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.
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:

Console says	It means	Fix
`found character '\t' that cannot start any token`	A tab where spaces belong	Delete the tab, retype spaces
`mapping values are not allowed here`	An unquoted `:` inside a value	Wrap the value in quotes
`could not find expected ':'`	A missing space after a colon, or bad indentation	Add the space; line up the indent

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

The safe editing habit

Copy the file first (or take a backup before a big change).
Edit in the File Manager with the language set to YAML.
Don't save past the syntax-error warning — fix it first.
Restart (or use the plugin's reload command) and watch the console for a clean load.
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.

Was this guide helpful?

More in this category

Getting started with Minecraft pluginsBeginnerTemplate 1,141 Set up EssentialsXBeginner 567 LuckPerms basicsIntermediate 434 Build a rank ladder with LuckPermsIntermediate 501 Roll back grief with CoreProtectIntermediate 467

View all

YAML without tears: editing plugin configs

Intermediate 233 5 min read

At a glance
You need	A plugin installed (so it has a config), and the File Manager
Plan	Any
Time	Ten minutes, then it's a reflex

The rules that matter

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

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.
Indentation must line up. Items at the same level need the same number of leading spaces. Nesting means more spaces than the line above.
A space after every colon. enabled: true, not enabled:true.
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.
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:

Console says	It means	Fix
`found character '\t' that cannot start any token`	A tab where spaces belong	Delete the tab, retype spaces
`mapping values are not allowed here`	An unquoted `:` inside a value	Wrap the value in quotes
`could not find expected ':'`	A missing space after a colon, or bad indentation	Add the space; line up the indent

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

The safe editing habit

Copy the file first (or take a backup before a big change).
Edit in the File Manager with the language set to YAML.
Don't save past the syntax-error warning — fix it first.
Restart (or use the plugin's reload command) and watch the console for a clean load.
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

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

Was this guide helpful?

More in this category

View all

YAML without tears: editing plugin configs

The rules that matter

Let the File Manager help you

Reading the error the console prints

The safe editing habit

Verify it works

Troubleshooting

Next steps

Falix Guides

Browse by topic

Only show guides for your app

YAML without tears: editing plugin configs

The rules that matter

Let the File Manager help you

Reading the error the console prints

The safe editing habit

Verify it works

Troubleshooting

Next steps