Common Mistakes with YAML and How to Avoid Them

YAML (YAML Ain't Markup Language) is everywhere in network automation, from Ansible playbooks to configuration templates. While its human-readable format makes it appealing, YAML's strict syntax rules can trip up beginners. Let's explore the most common YAML mistakes and how to avoid them.

Indentation Errors: The Silent Killer

The biggest source of YAML errors is incorrect indentation. YAML uses spaces (never tabs) to define structure, and every space matters.

Common Mistake: Mixing spaces and tabs or inconsistent spacing

# Wrong - inconsistent indentation
tasks:
  - name: Configure interface
      ios_config:
        lines:
          - interface GigabitEthernet0/1
         - ip address 192.168.1.1 255.255.255.0

# Correct - consistent 2-space indentation
tasks:
  - name: Configure interface
    ios_config:
      lines:
        - interface GigabitEthernet0/1
        - ip address 192.168.1.1 255.255.255.0

Solution: Configure your text editor to show whitespace characters and use spaces exclusively. Most editors can convert tabs to spaces automatically.

Quotation Mark Issues

YAML handles strings intelligently, but certain characters require explicit quoting to avoid parsing errors.

Common Mistake: Not quoting strings with special characters

# Wrong - colon in unquoted string breaks parsing
description: Interface to Building A: Main uplink

# Correct - quoted to preserve the colon
description: "Interface to Building A: Main uplink"

# Also correct - using single quotes
description: 'Interface to Building A: Main uplink'

Special characters that need quoting: :, {, }, [, ], -, |, >, and @ at the beginning of strings.

List Formatting Confusion

YAML supports two list formats, and mixing them incorrectly causes errors.

Common Mistake: Inconsistent list formatting

# Wrong - mixing formats
interfaces:
  - GigabitEthernet0/1
    GigabitEthernet0/2  # Missing dash
  - GigabitEthernet0/3

# Correct - consistent dash format
interfaces:
  - GigabitEthernet0/1
  - GigabitEthernet0/2
  - GigabitEthernet0/3

# Also correct - inline format
interfaces: [GigabitEthernet0/1, GigabitEthernet0/2, GigabitEthernet0/3]

YAML Troubleshooting Tips

When you encounter YAML errors, follow this systematic approach:

• Check indentation first: Count spaces carefully and ensure consistency
• Validate syntax: Use online YAML validators or python -c "import yaml; yaml.safe_load(open('file.yml'))"
• Look for special characters: Add quotes around strings containing colons, brackets, or other special symbols
• Watch for trailing spaces: These invisible characters can break parsing

Boolean and Number Gotchas

YAML automatically converts certain strings to booleans or numbers, sometimes unexpectedly.

# These all become boolean True
enabled: true
enabled: True
enabled: yes
enabled: on

# These become boolean False
enabled: false
enabled: False
enabled: no
enabled: off

# Force string interpretation with quotes
version: "1.0"  # String, not number
norway: "no"    # String, not boolean false

Multi-line String Mistakes

YAML offers two operators for multi-line strings: | (literal) preserves line breaks, while > (folded) converts them to spaces.

# Literal block - preserves line breaks
banner: |
  Welcome to Router01
  Unauthorized access prohibited
  Contact [email protected]

# Folded block - joins lines with spaces  
description: >
  This is a long description that
  spans multiple lines but becomes
  a single line in the output

What's Next

Now that you understand common YAML pitfalls, you're ready to dive into Jinja2 templating. In our next post, we'll explore how to combine YAML data structures with Jinja2 templates to create dynamic network configurations, building on the solid YAML foundation you've established.