YAML Troubleshooting

This page serves as a reference guide for YAML troubleshooting issues and tips.

YAML Troubleshooting Issues and Tips

Invalid Byte Order Mark

- Invalid use of BOM
⇔
- Inside a document.

A Byte Order Mark should not appear inside the document. Try to change it to:

⇔# Comment only.

This stream contains no documents, only comments.

Invalid Use of Reserved Indicator

key1: @text
 key2: `text

A Reserved Indicator can’t start a plain scalar.

Invalid Escaped Character

Bad escapes:
  "\c
   \xq-"

c is not a valid escape character. q and – are invalid hex digits.

=> You can use these escaped characters instead:

- "Fun with \\"
- "\" \a \b \e \f" #escape character
- "\n \r \t \v \0" #escape character
- "\ \_ \N \L \P \ #escape character
  \x41 \u0041 \U00000041" #hex digits

Invalid repeated YAML directory

Even though both instances have the same version number, using multiple “YAML” directives for the same document is an error.

%YAML 1.2
%YAML 1.1
  foo

The YAML directive should only be used once per document. You may change it to:

%YAML 1.3 # Attempt dissect
           # with a warning
---
"text"

Invalid Repeated TAG directive

Even if both occurrences give the same prefix, specifying more than one “TAG” directive for the same handle in the same document causes an error.

%TAG ! !foo
%TAG ! !foo
  bar

In the same document, the TAG directive can only be used once per handle.

%TAG !yaml! tag:yaml.org,2000:
---
!yaml!str "text"

Invalid Verbatim Tags

- !<!> foo
- !<$:?> bar

Verbatim tags aren’t resolved, so ! is invalid.

The $:? tag is neither a global URI tag nor a local tag starting with ‘!’.

Invalid Block Scalar Indentation Indicators

- |
·· ## Error 1
·text
- >
··text
·text ## Error 2
- |2
·text ## Error 3

Error 1: A leading all-space line must not have too many spaces.

Error 2: The following text line must not be less indented.

Error 3: The text is less indented than the indicated level.

Unquoted Scalar

There are a few exceptions to the rule that you can put anything into an unquoted scalar. A mapping is indicated by a colon followed by a space (or newline) “:“. A remark begins with a space followed by the pound symbol “#“.

As a result, the following code will result in a YAML syntax error:

windows_drive: c:

But this will work just fine:

windows_path: c:\windows

Preserved Colon

You should use colons followed by a space or the end of the line to quote hash values:

windows_drive: 'c:'

The difference between single and double-quotes is that you may use escapes in double quotes:

test: "a \t TAB and a \n NEW"

Preserved Colon – 2nd Case

You should use colons followed by a space or the end of the line to quote hash values:

test: "an escaped \' single quote"

Ansible also uses the variable name “{{ var }}”. If a value following a colon begins with a “{“, YAML will interpret it as a dictionary, therefore quote it as follows:

test: "{{ variable }}"

If your value begins with a quotation, you must quote all values, not just a portion. Here are some more examples of how to cite things correctly:

test: "{{ variable }}/additional/string/literal"
test2: "{{ variable }}\\backslashes\\are\\also\\special\\characters"
test3: "It must all be quoted, even if it's simply a string literal."

Invalid Characters of an Unquoted Scalar

test: "E:\\path\\"rest\\of\\path

In addition to ‘ and ” there are a few special (or reserved) characters that cannot be used as the initial character of an unquoted scalar: [] {} > | * & ! % # ` @ ,.

You should also be aware of the following: ? : -. They are permitted at the start of a string in YAML if there’s a non-space character after it, but YAML processor implementations differ, so it’s recommended to use quotes.

Additional Information

Check out our Language Features page, or FAQs to learn more. You can also find helpful content at yaml.org

%d bloggers like this: