How to Find and Fix YAML Errors in Minecraft Plugin Configs

Diagnose and fix YAML syntax errors in Minecraft Java plugin config files — indentation, tabs, colons, quotes, and validation tools.

YAML is the format used by virtually every Minecraft plugin (config.yml, spigot.yml, bukkit.yml, paper.yml, etc.). It's clean to read but brutally strict about whitespace — a single misplaced tab can prevent a plugin from loading and dump a wall of stack traces in your Console.

Most YAML errors fall into five categories: tabs vs spaces, missing colons, unquoted special characters, broken indentation, and unbalanced lists.

How YAML Errors Appear

In your Console, you'll see something like:

[ERROR] Could not load 'plugins/SomePlugin.jar' in folder 'plugins'
org.bukkit.configuration.InvalidConfigurationException: while parsing a block mapping
 in 'reader', line 12, column 3:
       enabled: true
       ^
expected <block end>, but found '<scalar>'
 in 'reader', line 14, column 3:
       prefix: "<<"
       ^

The line number in the error tells you exactly where to look — but the cause is often a few lines above.

The Five Most Common YAML Mistakes

Tabs Instead of Spaces

YAML does not allow tabs for indentation, ever. Every level must use spaces (2 or 4, consistently).

# WRONG (tab character)
settings:
→enabled: true

# CORRECT (2 spaces)
settings:
  enabled: true

The #1 cause of YAML errors. If you copy-paste from a website, it can silently inject tabs. Always check.

Missing Colons

Every key must end with a colon followed by a space.

# WRONG
server-name My Server

# CORRECT
server-name: My Server

Unquoted Special Characters

Strings containing :, #, [, ], {, }, &, *, !, |, >, ', ", %, @, or backslash must be quoted.

# WRONG (colon inside unquoted string)
motd: Welcome: enjoy your stay

# CORRECT
motd: "Welcome: enjoy your stay"

# WRONG (# is treated as comment start)
prefix: <#chat#>

# CORRECT
prefix: "<#chat#>"

Inconsistent Indentation

All keys at the same level must have the same indentation.

# WRONG (extra space on option2)
settings:
  option1: true
   option2: false

# CORRECT
settings:
  option1: true
  option2: false

Broken Lists

YAML lists use - followed by a space. Indentation must be consistent.

# WRONG (no space after dash)
worlds:
  -world
  -world_nether

# CORRECT
worlds:
  - world
  - world_nether

# Also correct (compact form)
worlds: [world, world_nether]

Fix It

Read the Console error

In the XGamingServer Panel, open Console and find the most recent Could not load or InvalidConfigurationException message. Note the file and line number.

Open the file in the panel editor

Click Files in the sidebar. Navigate to the file from the error and open it.

Validate the file online

Copy the entire file content. Paste it into yamllint.com and click Go. The validator highlights every error with a line number.

Fix the line(s)

Common fixes (in order of frequency):

Replace tabs with 2 spaces
Add missing colons
Quote strings with special characters
Fix indentation alignment
Add the space after - in lists

Save and reload

Click Save Content. Then either:

Restart the server (safest)
Or run the plugin's reload command (e.g., /luckperms reload, /essentials reload)

Prevention Tips

Tip	Why
Use a code editor with YAML highlighting (VS Code, Notepad++, Sublime)	Catches errors before upload
Set your editor to insert spaces, not tabs	Eliminates the #1 cause
Use 2-space indentation consistently	Standard for Minecraft plugins
Always edit YAML in a real editor, not Notepad	Notepad can mangle line endings and encoding
Validate before uploading large config changes	yamllint.com is free
Make a backup of working configs	Roll back instantly if something breaks

Mistake	Fix
Using Notepad and saving as `.yml.txt`	Use Files panel editor or VS Code
Mixing tabs and spaces in the same file	Convert all to spaces
Forgetting to restart after saving	YAML loads at startup or reload
Editing while server is running	Some files (`server.properties`) get overwritten on shutdown
Pasting Word/Google Docs content	Smart quotes break YAML — paste from plain text
Unquoted Minecraft color codes (`§`, `&`)	Always quote: `motd: "&aHello"`

Common Mistakes — One More Time

The single most useful rule: if a YAML file just stopped working, the problem is almost always indentation or a tab. Start there.