YAMLのインデントエラーを直す - 3大エラーメッセージ別ガイド

Kubernetes マニフェストや GitHub Actions、docker-compose を編集していてmapping values are not allowed in this context に遭遇したら、 原因はタブ文字・インデント不揃い・コロン後のスペース忘れのどれかがほぼ全てです。 この記事ではパーサーが実際に出す3つのエラー文言から逆引きで直します。

This guide maps the three most common YAML parser errors — "mapping values are not allowed in this context", "could not find expected ':'", and "found character '\t' that cannot start any token" — to their root causes, with real examples from Kubernetes, GitHub Actions, and docker-compose.

TL;DR

• mapping values are not allowed in this context → 値の中の : (コロン+スペース)を引用符で囲む、またはキーのインデントを揃える
• could not find expected ':' → 複数行に割れたキー、またはコロンの書き忘れ。直前の行を確認
• found character '\t' that cannot start any token → タブ文字。スペースに一括置換
• YAML のインデントはスペースのみ。タブは仕様で禁止(YAML 1.2)
• コロンの後には必ずスペースが必要(key:value は1つの文字列扱い)
• リスト(-)とマップを混在させるときは - の位置を親キーに揃える

1. mapping values are not allowed in this context / Unquoted colon in a value

PyYAML(Python)や kubectl が出す典型的なエラーです。

yaml.scanner.ScannerError: mapping values are not allowed in this context
  in "config.yaml", line 3, column 23

最頻出の原因は、値の中に「コロン+スペース」が引用符なしで入っていることです。 パーサーは2つ目の : を「新しいマッピングの開始」と解釈し、その場所では マッピングを開始できないためエラーになります。GitHub Actions の run: や K8s の description: で頻発します。

# NG: echo の引数に「時刻: 」が含まれる
- name: Show time
  run: echo Started at: $(date)

# OK: 値全体をクォートする
- name: Show time
  run: 'echo Started at: $(date)'

もう1つの原因はインデント不揃いです。キーが親より浅い・深い位置にずれると、 パーサーはそこを「前の値の続き」と見なした後でコロンに出会い、同じエラーを出します。

# NG: image が containers の子なのに 1 スペース深い
spec:
  containers:
    - name: app
       image: nginx:1.27   # ← name と揃っていない

# OK: 同じブロックのキーは同じ列に揃える
spec:
  containers:
    - name: app
      image: nginx:1.27

This error means the parser found : where a mapping cannot start: either an unquoted colon inside a value (quote the whole value) or a key whose indentation does not match its siblings (align it).

2. could not find expected ':' / Missing or broken colon

yaml.scanner.ScannerError: while scanning a simple key
  in "docker-compose.yml", line 4, column 1
could not find expected ':'
  in "docker-compose.yml", line 5, column 1

キーにコロンを付け忘れたか、キーが改行で分断されたときのエラーです。 YAML の単純キーは1行に収まる必要があるため、コロンが見つからないまま次の行に到達すると失敗します。 エラーが指す行の1つ前の行を確認するのがコツです。

# NG: ports のコロン忘れ
services:
  web:
    image: nginx
    ports          # ← ここが原因(エラーは次行を指す)
      - "8080:80"

# OK
services:
  web:
    image: nginx
    ports:
      - "8080:80"

また key:value のようにコロンの直後のスペースを忘れると、 エラーにならず「key:value という1つの文字列」として静かに誤解釈されるケースがあります (フローマッピング内ではエラーになります)。image: nginx のように コロンの後には必ずスペースを置いてください。

The parser scanned a key but never met its colon — usually a forgotten : on the previous line. Also note that key:value without a space is parsed as one plain scalar, not a key-value pair.

3. found character '\t' that cannot start any token / Tab characters

yaml.scanner.ScannerError: while scanning for the next token
found character '\t' that cannot start any token
  in "deployment.yaml", line 7, column 1

YAML 1.2 仕様はインデントをスペースのみと定めています。エディタの幅設定で 見え方が変わるタブは構造を曖昧にするため、仕様レベルで禁止されています。 見た目では区別できないので、エディタで不可視文字を表示(VS Code:"editor.renderWhitespace": "all")するか、一括置換してください。

# タブをスペース2個に一括置換(macOS/Linux)
sed -i 's/\t/  /g' deployment.yaml

# 再発防止: .editorconfig をリポジトリ直下に置く
[*.{yml,yaml}]
indent_style = space
indent_size = 2

YAML forbids tabs in indentation by spec. Replace them with spaces and add an.editorconfig so your editor never inserts tabs in .yaml files again.

4. リストとマップの混在ルール / Mixing sequences and mappings

エラーは出ないのに kubectl apply や CI が意図通り動かない場合、 リスト(シーケンス)とマップの混在ミスが疑わしいです。ルールは2つだけです。

• - は親キーと同じ列、またはそれより深い列に置く(同じ列でも合法)
• リスト項目がマップを持つ場合、2行目以降のキーは1行目のキーの列に揃える(- の列ではない)

# docker-compose: environment はリストかマップのどちらか一方
# NG: リスト記法とマップ記法の混在
environment:
  - TZ=Asia/Tokyo
  DB_HOST: db        # ← リストの途中にマップは置けない

# OK: リストに統一
environment:
  - TZ=Asia/Tokyo
  - DB_HOST=db

# OK: マップに統一
environment:
  TZ: Asia/Tokyo
  DB_HOST: db

GitHub Actions では steps: 配下の - name: / uses: /with: の揃え方、K8s では env: 配下の - name: /value: の揃え方で同じパターンのミスが起きます。迷ったらJSON / YAML Converter で一度 JSON に変換すると、 構造(配列かオブジェクトか)が一目で分かります。

A sequence item's mapping keys must align with the first key after -, and you cannot mix list items and mapping keys at the same level. Converting to JSON is a quick way to see the actual structure.

まとめ / Summary

再発防止には、エディタに不可視文字を表示させること、.editorconfig で 2スペースを強制すること、そして編集後に毎回バリデータへ通すことが効きます。

Almost every YAML syntax error traces back to tabs, misaligned indentation, an unquoted colon in a value, or a missing space after a colon. Read the error line number, check the line above it too, and validate after every edit.

関連ツール / Related tools

• YAML Formatter / Validator
• JSON / YAML Converter
• Diff Checker

関連ガイド / Related guides

• JSON Unexpected token エラーの直し方 / Fix JSON parse errors
• JSON Schema で型を保証する基本 / JSON Schema basics
• git push rejected の直し方 / Fix non-fast-forward push