Editing Bukkit Plugin Configuration Files (YAML)

Many Minecraft bukkit plugins store their configuration settings within text files in the YAML format. These files have the .yml or .yaml file extension. This article covers how you can edit these files and ensure that they are in the correct format. An incorrectly formatted YAML file can cause a plugin to fail to load or behave badly. They can even prevent a server from starting.

What is YAML?

YAML stands for YAML Ain't Markup Language. It is a human readable serialized data language, or more simply, a data structure in text form that is easy to read. It is designed to use most of the text as data and have as little markdown as possible. Here’s an example:

# I am a comment line
string: This is a text string #Comments can appear in line too
number: 15
array type 1: [string1,string2,"string3: With a special character!"]
array type 2:
  - string1
  - string2
  - "Some special characters like double-quotes \" need to be escaped"
associative array type 1:
  key1: value1
  key2: value2
  key3: [can, also, be, an, array]
    key4-1: "You can nest associative arrays!"
associative array type 2: {key1: value1, key2: value2}
folded text: >
  These separate
  lines will be merged
  into one
  A blank line starts
  a new paragraph
literal text: |
  The linebreaks for
  this text will be preserved.
  The indent on the first line
  will be removed from each line
    extra indentation will be preserved

For comparison, here’s the almost equivalent in another serialized data language, JSON:

  "string": "This is a text string",
  "number": 15,
  "array type 1": [
    "string3: With a special character!"
  "array type 2": [
    "Some special characters like double-quotes \" need to be escaped"
  "associative array type 1": {
    "key3": [
    "key2": "value2",
    "key1": "value1",
    "key4": {
      "key4-1": "You can nest associative arrays!"
  "associative array type 2": {
    "key2": "value2",
    "key1": "value1"
  "folded text": "These separate lines will be merged into one\nA blank line starts a new paragraph\n",
  "literal text": "The linebreaks for\nthis text will be preserved.\nThe indent on the first line\nwill be removed from each line\n  extra indentation will be preserved"

As you can see, there’s a lot more bracketing and double-quotes in JSON but that also means you can scrunch it down to this:

{"string":"This is a text string","number":15,"array type 1":["string1","string2","string3: With a special character!"],"array type 2":["string1","string2","Some special characters like double-quotes \" need to be escaped"],"associative array type 1":{"key3":["can","also","be","an","array"],"key2":"value2","key1":"value1","key4":{"key4-1":"You can nest associative arrays!"}},"associative array type 2":{"key2":"value2","key1":"value1"},"folded text":"These separate lines will be merged into one\nA blank line starts a new paragraph\n","literal text":"The linebreaks for\nthis text will be preserved.\nThe indent on the first line\nwill be removed from each line\n  extra indentation will be preserved"}

Not very easy to read. YAML on the other hand uses line indentation to denote if a data item is part of another. With less furniture it has a cleaner look and is easy to read. On the flip-side, it’s also easy to break the format if you don’t know the rules.

Basic YAML Rules

You can find more rules and examples at http://www.yaml.org/spec/1.2/spec.html#Preview

  • Whitespace indentation is used to denote structure. However, the Tab character must not be used. You can indent by any number of spaces but most plugins use YAML formatted with 2 space characters for each indentation ‘level’
  • Comments are denoted by a number or ‘hash’ symbol: #
    Comments can appear on a line of their own or at the end of any line. There must be whitespace between the data and the comment
  • List (Array) items are denoted by a leading hyphen: -
    List items may also be enclosed in square brackets [ ] and separated by a comma and a space
  • Associative Array items are represented using a key and its value separated by a colon and a space key: value
    They may also be enclosed inside curly braces { } and separated by a comma and a space
  • The text used for a key or a value does not need to be inside single-quotes ' or double-quotes ". However you can use them if you want to include leading or trailing whitespace
    You will also want to use double-quotes if you want a string to contain some of YAML’s control characters
  • Two associative array items inside the same data item on the same level cannot have the same key

Editing YAML Files in Multicraft Control Panel

The StickyPiston Multicraft Control Panel has been configured to look for configuration files on your server in the plugins/ folder and all sub-folders. We have also configured it to search in specific special cases where the config files are stored in deeper sub-folders or in other locations.

You can view a list of all the config files found by the control panel by selecting Files>>Config Files from the left hand menu. You can use the filter boxes at the top of the list to help find a specific config file. Many plugins place their config files into a sub-folder with the same name as the plugin. We put the file path into the Description column, so typing the plugin name into the Description filter box should show all the configs for that plugin. Click on the config file in the Name column to edit the file.

The CodeMirror Editor

We have replaced the default file editor with CodeMirror. This provides some useful extra features:

  • Code Highlighting
  • Auto Indentation
  • Line Numbering
  • Full Screen Mode (F11)
  • Bracket and Tag Matching
  • Search (Ctrl+F)

Your code will also be automatically parsed and checked for errors as you type. If the code is valid then it will display in a tree structure below the editor. If there is an error, it will be displayed instead. The parser does not catch all errors, we suggest that you also use the YAMLlint or Online YAML Parser tool. See Checking Your YAML Code below

When you have finished editing the file, click the Save button below the editor.

Downloading to your Computer and Editing the File

You can download the config file using FTP. Check out our guide: https://stickypiston.co/account/knowledgebase.php?action=displayarticle&id=8

We recommend using a text editor that supports code highlighting. Notepad++ is free and can be obtained here: http://notepad-plus-plus.org/download/

Configuring Notepad++ Tab Settings for YAML Files

By default pressing the ‘Tab’ key in a YAML file will insert a tab character. However, most YAML files used by Minecraft mods and plugins use a double-space to indent the text. Since YAML files use indentation to denote structure, it’s a good idea to force Notepad++ to input 2 spaces instead of a tab when the tab key is pressed. This will help prevent YAML parsing errors.

  1. Settings>>Preferences
  2. In the list on the left highlight Tab Settings
  3. Scroll down the list on the right, find and highlight yaml
  4. Un-check the Use default value box
  5. Check the Replace by space box
  6. Click on the number next to Tab size:
  7. In the box that appears, change the number to 2 and press enter
  8. Click the Close button

Now when you open a YAML file, the indents will be correctly displayed and when you press tab it will insert two spaces.

Checking Your YAML Code

Most text editors will not check that your code is valid. You can use an external tool like http://www.yamllint.com/ or https://yaml-online-parser.appspot.com/ to check your code.

Copy the text from your editor and paste it into the YAMLlint website and click the Go button. It will then tell you if there are any errors and the line number that it detected it on. YAMLlint will restructure your YAML code and remove comments. Fix the code in your editor and then paste it into YAMLlint to try again. yaml-online-parser.appspot.com will parse your code as you type.

Common YAML Parser Errors

Duplicate Key

duplicated mapping key at line 3, column 27:
      child key: duplicate key

You have placed two items with the same key inside the same item at the same level

parent key:
  child key: first appearance
  child key: duplicate key

Remove one of the duplicates

Bad Indentation

bad indentation of a mapping entry at line 3, column 2:
     Team B: 4

A line’s indentation does not match the current indentation level

  Team A: 10
 Team B: 4
  Team C: 7

Correct the indentation of the line so that it matches the ones above

Missing a Space Between a ‘key: value’ pair

On the first item in an associative array

bad indentation of a mapping entry at line 3, column 9:
      Team B: 4

Note that it throws a bad indentation error on the semi-colon of the line after

  Team A:10
  Team B: 4
  Team C: 7

On an item in the middle of an associative array

can not read a block mapping entry; a multiline key may not be an implicit key at line 4, column 9:
      Team C: 7

Note that it throws a can not read implicit mapping pair on the semi-colon of the line after

  Team A: 10
  Team B:4
  Team C: 7

On the last item in an associative array

can not read an implicit mapping pair; a colon is missed at line 4, column 11:
      Team C:7

This one gives the error on the offending line

  Team A: 10
  Team B: 4
  Team C:7

Tab Character in the Code

The CodeMirror YAML parser will not give you this error. Different YAML parsers will return errors along the lines of:

while scanning for the next token
found character '\t' that cannot start any token
  in "<unicode string>", line 6, column 1:
        - value
found character '/t' that cannot start any token in "<unicode string>", line 6, character 1
found character that cannot start any token while scanning for the next token at line 6 column 1
found a tab character that violate intendation
  • 3 Users Found This Useful

Was this answer helpful?

 Print this Article

Also Read

Create a MySQL database for Bukkit Plugins

Some plugins require the use of a MySQL database. Because of this we have a dedicated database...

How To: Set up the Essentials plugin with Group Manager

An overview of the Group Manager permissions plugin. This article will help you install the...

Installing Factions plugin

The MassiveCraft Factions is a popular PVP plugin allowing your to claim land, build bases,...

Setting Entity Ranges in spigot.yml to match Vanilla Minecraft

Entity Ranges in Spigot By default, Spigot sets the distances from players that monsters and...