# How to Find and Fix YAML Errors in Minecraft Plugin Configs (/docs/minecraft/find-fix-yaml-errors)



import { Step, Steps } from 'fumadocs-ui/components/steps';

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 [#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 [#the-five-most-common-yaml-mistakes]

<div className="fd-steps">
  <div className="fd-step">
    Tabs Instead of Spaces [#1-tabs-instead-of-spaces]

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

    ```yaml
    # 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.
  </div>

  <div className="fd-step">
    Missing Colons [#2-missing-colons]

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

    ```yaml
    # WRONG
    server-name My Server

    # CORRECT
    server-name: My Server
    ```
  </div>

  <div className="fd-step">
    Unquoted Special Characters [#3-unquoted-special-characters]

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

    ```yaml
    # 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#>"
    ```
  </div>

  <div className="fd-step">
    Inconsistent Indentation [#4-inconsistent-indentation]

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

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

    # CORRECT
    settings:
      option1: true
      option2: false
    ```
  </div>

  <div className="fd-step">
    Broken Lists [#5-broken-lists]

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

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

    # CORRECT
    worlds:
      - world
      - world_nether

    # Also correct (compact form)
    worlds: [world, world_nether]
    ```
  </div>
</div>

Fix It [#fix-it]

<Steps>
  <Step>
    Read the Console error [#read-the-console-error]

    In the [XGamingServer Panel](https://panel.xgamingserver.com), open **Console** and find the most recent `Could not load` or `InvalidConfigurationException` message. Note the **file** and **line number**.
  </Step>

  <Step>
    Open the file in the panel editor [#open-the-file-in-the-panel-editor]

    Click **Files** in the sidebar. Navigate to the file from the error and open it.
  </Step>

  <Step>
    Validate the file online [#validate-the-file-online]

    Copy the entire file content. Paste it into [yamllint.com](https://www.yamllint.com/) and click **Go**. The validator highlights every error with a line number.
  </Step>

  <Step>
    Fix the line(s) [#fix-the-lines]

    Common fixes (in order of frequency):

    1. Replace tabs with 2 spaces
    2. Add missing colons
    3. Quote strings with special characters
    4. Fix indentation alignment
    5. Add the space after `- ` in lists
  </Step>

  <Step>
    Save and reload [#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`)
  </Step>
</Steps>

Prevention Tips [#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      |

Specific Fixes for Common Files [#specific-fixes-for-common-files]

paper-world-defaults.yml (multiple worlds) [#paper-world-defaultsyml-multiple-worlds]

Each world inherits from `default:`. Make sure `default:` and `world_<name>:` are at the same indentation level.

bukkit.yml spawn-limits [#bukkityml-spawn-limits]

The keys are case-sensitive: `monsters`, `animals`, `water-animals`, `water-ambient`, `axolotls`, `ambient`. Anything else gets ignored.

LuckPerms group YAML [#luckperms-group-yaml]

Permission lists use `- '<permission>'` with single quotes — special characters like `*` must be quoted.

Common Mistakes [#common-mistakes]

| 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 [#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.

Related Guides [#related-guides]

* [Find / Fix JSON Errors](/docs/minecraft/find-fix-json-errors)
* [Edit Bukkit / Spigot / Paper Configs](/docs/minecraft/edit-bukkit-spigot-paper-configs)
* [Server Properties](/docs/minecraft/server-properties)
* [Server Won't Start](/docs/minecraft/fix-server-wont-start)
* [Common Issues](/docs/minecraft/common-issues)