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.

よくある質問 / FAQ

mapping values are not allowed in this context の原因は?

値の中に「コロン+スペース」が引用符なしで含まれているか、キーのインデントが前後の行と揃っていないことが原因です。値をクォートで囲むか、インデントを揃えれば解決します。

YAMLでタブ文字は使える?

インデントには使えません。YAML仕様(YAML 1.2)はインデントをスペースのみと定めており、タブを使うと found character '\t' that cannot start any token エラーになります。

YAMLのインデントは何スペースが正しい?

仕様上は1以上なら何スペースでも有効ですが、同じブロック内で揃っていることが必須です。慣例は2スペース(Kubernetes・GitHub Actions・docker-compose とも2スペースが標準)。

Why does YAML reject tab characters?

The YAML 1.2 spec only allows spaces for indentation because tab width is ambiguous across editors. Any tab used as indentation raises "found character '\t' that cannot start any token".

関連ツール / 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