Common Gotchas

8 min read · Beginner
You will learn
  • The 6 mistakes that cause 90% of YAML errors
  • The Norway / YES-NO boolean trap and how to avoid it
  • Why duplicate keys are silently overwritten

When working with YAML files in semiconductor design, even small mistakes can cause big problems. A missing space or wrong indentation might prevent your design tools from running correctly. Learning to identify and fix common YAML mistakes will save you time and frustration.

Test Yourself First

Before reading the explanations, try to find the bugs! Each challenge has one error — click the line you think is wrong:

Interactive: Find the Bug!

Click the line with the error — then read why it is wrong and how to fix it

Challenge 1 of 7 Missing space after colon
1 # My chip settings
2 chip_name:"My Processor"
3 speed: 100

Look for a colon that is missing its space.

Example: Finding Multiple Errors

Let’s examine a real semiconductor configuration file that has several problems. Can you spot them all?

The broken file:

# Semiconductor Design Configuration
project_info:
   name: 5G Modem Design
     team_lead:"Sarah Chen" # Missing space!
   version: 2.0
   version: 3.0 # Duplicate key!
testing:
   functional_test: TRUE # Wrong format!
   performance_test: yes
   power_test: True # Inconsistent!

This file has four errors:

  1. name: 5G Modem Design — needs quotes (contains a space)
  2. team_lead:"Sarah Chen" — missing space after colon, and wrong indentation (4 spaces instead of 2)
  3. version appears twice — duplicate key!
  4. TRUE, yes, True — use lowercase true / false everywhere
Footnote · the Norway bug

You may read online that YAML turns NO, yes, on, off into booleans — the famous "Norway problem" where the country code NO becomes false. Modern YAML (1.2) only accepts lowercase true and false, so this is only a trap in older YAML 1.1 files. Rule of thumb: always lowercase, always quote any single-word value that could be ambiguous.

The corrected file:

# Semiconductor Design Configuration
project_info:
·· name: "5G Modem Design"
·· team_lead: "Sarah Chen"
·· version: "3.0"
testing:
·· functional_test: true
·· performance_test: true
·· power_test: true
· = one space

Every error is fixed: quotes added, space after colon, duplicate removed, booleans all use lowercase true.

Error Messages and What They Mean

When YAML finds an error, it shows a message. These messages can be confusing at first, but they all point to common problems. Click each one to learn what it means:

Q "mapping values are not allowed here" ▸
Q "found duplicate key" ▸
Q "expected <block end>, but found '<scalar>'" ▸
Q "could not find expected ':'" ▸

YAML Validation Checklist

Before using any YAML file, check these items:

Syntax Checklist

  • ✓ Indentation: Consistent spaces (2 or 4), no tabs
  • ✓ Colons: Space after every colon
  • ✓ Lists: Consistent dash formatting
  • ✓ Quotes: Used for text with spaces or special characters
  • ✓ Booleans: Using true/false (lowercase)
  • ✓ No duplicate keys in the same section

Content Checklist

  • ✓ Required fields: All necessary settings present
  • ✓ Valid values: Settings match expected formats
  • ✓ Units specified: Include units in key names (like frequency_mhz)
  • ✓ Comments helpful: Explain complex settings
  • ✓ Consistent naming: Follow snake_case naming

Building Good Validation Habits

Before Saving Your YAML File

  1. Visual inspection: Does the structure look right?
  2. Check indentation: Are all levels consistent?
  3. Validate syntax: Use an online validator
  4. Test with tools: Try loading it in your design tools

When Sharing YAML Files

  1. Include documentation: Explain the structure
  2. Validate first: Don’t share broken files
  3. Use version control: Track changes properly
  4. Include examples: Show how to use the configuration

Key takeaways

Proper YAML validation helps you:

  • ✓ Avoid tool errors: Prevent design tools from failing
  • ✓ Save debugging time: Catch mistakes early
  • ✓ Share confidently: Know your files work correctly
  • ✓ Maintain quality: Keep professional standards
← Previous Next: Validation & Debugging →