巧匠Developer Cheatsheet
Config Formats

YAML Gotchas: Type Coercion, Indentation and Multiline Strings

YAML files that "look right but run wrong" usually fail in three places: silently coerced scalars, misplaced indentation, and ambiguous multiline strings. This guide dissects each trap with detection methods and a toolchain.

By 巧匠 Team·8 min read·Updated 2026-08-31

Type coercion: the biggest silent bomb

YAML infers scalar types automatically, and many values that "look like strings" get silently converted: `no`/`na`/`n` become the boolean false (the famous Norway problem), `on`/`off`/`yes` become true/false, `0733` becomes octal, and `1.10` becomes the number 1.1.

The result is config that "looks right but runs wrong": version numbers lose precision, country codes turn into booleans. Unless you explicitly want a number/boolean/null, quote every scalar — the single most stress-reducing YAML rule.

country: no          # 实际是 false，不是挪威！
country: "no"       # 这才是字符串
version: 1.10       # 变成数字 1.1
version: "1.10"    # 字符串，安全

When quoting is mandatory

Three classes of values must be quoted: ① anything that could be coerced to a number/boolean/null (`no`, `on`, `1.10`, plus `2026-01-01`, which parses as a date object); ② values starting with special characters (`*` `&` `!` `%` `@`); ③ values containing "colon + space" or ` #`.

The date trap deserves emphasis: `date: 2026-01-01` is a date object in most parsers, not a string, and it surfaces in a totally different shape during log debugging. Write `date: "2026-01-01"` for a string.

date: 2026-01-01      # 日期对象，不是字符串
date: "2026-01-01"   # 字符串
value: a: b           # 语法错误（冒号+空格）
value: "a: b"        # 正确

Indentation: one level off, data lands elsewhere

YAML accepts spaces only, never tabs (a tab is a hard syntax error); sibling keys must align; content after a list marker `- ` belongs to a child level. One level off and data silently lands under the wrong node — most parsers never complain.

Two frequent details: a space must follow the colon (`key:value` is invalid), and a comment `#` needs a preceding space or it becomes part of the value. A YAML language server (e.g. Red Hat YAML for VSCode) flags these live.

server:
  host: 0.0.0.0     # 缩进 2 空格，属于 server
  ports:
    - 80            # 列表项再缩进一级
    - 443
# key:value 错 → key: value 对

Multiline strings: | vs >

The pipe `|` keeps newlines (literal block); the fold `>` collapses newlines into spaces (folded block); adding `-` strips the trailing newline (`|-`, `>-`). Use `|` for scripts, certificates and SQL; use `>` for long prose.

The indentation baseline is set by the first line: every line in the block must be indented deeper than the parent key and consistently — this is exactly why "it looks aligned but still errors": you compared against the wrong level.

script: |
  #!/usr/bin/env bash
  set -euo pipefail
  echo "ok"
desc: >
  这是一段很长的说明文字，
  换行会被折叠成空格。
sql: |-
  SELECT *
  FROM users;

Anchors, aliases and merge keys

An anchor `&name` marks a node, an alias `*name` references it, and `<<:` merges a mapping into the current key — this is how docker-compose reuses shared config.

Two limits to remember: lists cannot be merged with `<<`, only referenced whole; an alias is a reference, not a copy, so changing one place changes all. Bonus trap: unquoted `80:80` parses as a sexagesimal (base-60) number under YAML 1.1 — always quote port mappings as `"80:80"` in compose files.

common: &common
  image: nginx:1.27
  restart: unless-stopped
web:
  <<: *common
  ports:
    - "80:80"

Debugging toolchain and checklist

Validate before shipping: yamllint for style and structure, the consuming tool itself (`docker compose config`, `kubectl --dry-run`), or a one-liner `yaml.safe_load` in Python to confirm what the parser actually sees.

Debugging principle: the reported line usually marks where the problem surfaced, while the real mistake sits a few lines above in indentation or quoting. Checklist: quote scalars, spaces only, space after the colon, pick the right `|`/`>` block, quote port mappings, run a parser before committing.

yamllint config.yaml
docker compose config        # 解析并规范化输出
kubectl apply --dry-run=client -f manifest.yaml
python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" config.yaml

More guides

Git Accident Recovery: Fix Wrong Commits, Wrong Branches and Deleted BranchesThe scariest moment in daily work is "oh no, I messed up a commit or branch". This guide gives copy-ready recovery commands for real accident scenarios, with clear safety boundaries for each.Docker Image Slimming: 5 Steps from 1.2GB to 120MBBigger images mean slower pulls, larger attack surface and higher storage cost. This guide gives 5 immediately applicable slimming steps, each with a reusable Dockerfile snippet and a verification command.Nginx 502 Bad Gateway? Locate It in 5 StepsA 502 means Nginx itself is fine but got an invalid response from the upstream (backend/proxy). This guide gives the shortest path: process → config → timeout → resources → logs.Linux Disk Full: Locate the Real Culprit with df, du and lsofA "No space left on device" error does not mean you should delete files at random. This guide walks through the full path — filesystem water level, directory drill-down, and "deleted but still held" files — plus a safe cleanup order that will not destroy data.Linux CPU at 100%: the Shortest Path from top to the Thread Stack"Restart fixes everything" is the most expensive option when CPU is pegged. This guide gives a reusable path: classify the load, pin the thread, capture what it is executing, then act — with dedicated tools for Java, Python and Go.MySQL Slow Query Tuning: Slow Log, EXPLAIN and Indexing"The database is slow" usually means a handful of slow SQL statements. This guide offers a repeatable flow: use the slow log to circle the most expensive queries, read the plan with EXPLAIN, decide whether an index pays off, and spot the most common index-defeating patterns.Redis Slowdown Playbook: Big Keys, Blocking Commands and EvictionRedis processes commands on a single thread, so one blocking hotspot slows the whole instance. This guide follows the order "memory level → big keys → blocking commands → eviction and persistence", each step with copy-ready commands.Kubernetes CrashLoopBackOff: Diagnose a Restart-Looping Pod in 5 StepsCrashLoopBackOff is not one error but a state: the container dies on start, and Kubernetes retries with backoff. This guide gives the shortest path — exit code → previous logs → probes → resources → dependencies.SSH Passwordless Login: from ssh-keygen to Permission deniedPasswordless SSH boils down to one sentence: put the public key into the remote authorized_keys. What blocks you is usually the three hidden gates — file permissions, the home directory, and SELinux. This guide covers the full setup and a step-by-step debugging path.Python Virtual Environments in Practice: venv, Dependency Pinning and Cross-Platform Gotchas"Works on my machine" usually means mixed environments. This guide builds a clean flow with the stdlib venv: create, activate, pin and reproduce — plus the three frequent pitfalls: Windows activation, version drift and cross-platform dependencies.VSCode Remote Development: Remote-SSH Setup and Connection DebuggingA weak laptop, code on an intranet server, GPUs in the cluster — Remote-SSH keeps the UI local while code and terminal run remotely, feeling native. This guide covers setup, passwordless auth, common connection failures and experience tuning.Bash Script Safety: set -euo pipefail and trap for Trustworthy ScriptsA Bash script that "finishes" is not a script that "worked": failed commands do not stop it, empty variables pass silently, and pipes hide upstream crashes. This guide fixes all of them with a copy-ready skeleton (set -euo pipefail + trap + quoting discipline).HTTP Caching in Practice: Configuring Cache-Control and ETag CorrectlyMisconfigured caching ends one of two ways: users never see updates, or origin traffic explodes. This guide covers the split between freshness and validation caching, the hashed-asset vs HTML strategy divide, plus ready-to-use Nginx config and verification commands.
← Back to Guides