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.

5. Kubernetes マニフェストの実例 / Kubernetes manifest errors

kubectl apply -f でよく出るのが error converting YAML to JSON です。containers: のリスト項目でインデントが1段でもずれると、YAML自体は読めても 期待する構造(配列)にならず、この変換エラーになります。

# NG: 2つ目のコンテナがリスト項目になっていない(- が抜けている)
spec:
  containers:
    - name: app
      image: myapp:1.0
      name: sidecar     # ← "-" がないので app の続きとして解釈される
      image: sidecar:1.0

# エラー
error converting YAML to JSON: yaml: line 7: mapping key "name" already defined at line 5

- を付け忘れると2つ目の要素が独立したリスト項目にならず、同じマップにname キーが二重に現れて already defined エラーになります。

# OK: 2つ目のコンテナにも "-" を付ける
spec:
  containers:
    - name: app
      image: myapp:1.0
    - name: sidecar
      image: sidecar:1.0

もう1つの典型例は env の value をクォートし忘れて数値やブール値扱いされるケースです。

# NG: value が文字列 "no" のつもりが真偽値 false と解釈される
env:
  - name: FEATURE_FLAG
    value: no

# error converting YAML to JSON: yaml: unmarshal errors:
#   line 3: cannot unmarshal bool into Go struct field EnvVar.value of type string

# OK: 明示的にクォートする
env:
  - name: FEATURE_FLAG
    value: "no"

kubectl apply reports error converting YAML to JSON when the YAML parses but does not match the expected shape — most often a missing - that collapses two list items into one map, or an unquoted value like no/on that YAML coerces into a boolean instead of a string.

6. GitHub Actions ワークフローの実例 / GitHub Actions workflow errors

GitHub Actions は構文エラーがあると実行前に Invalid workflow file として Actions タブに表示されます。steps: 配下のインデントミスが最頻出です。

# NG: 2つ目の step の "-" が steps: と同じ列(浅すぎる)
jobs:
  build:
    steps:
      - uses: actions/checkout@v4
    - run: npm test

# エラー(Actionsタブに表示)
Invalid workflow file: .github/workflows/ci.yml#L5
  (Line: 5, Col: 5): Unexpected value 'run'

# OK: すべての step の "-" を同じ列に揃える
jobs:
  build:
    steps:
      - uses: actions/checkout@v4
      - run: npm test

on: や jobs: の階層を誤ってネストしすぎるパターンもあります。jobs: の子であるべき build: が1段深くなると、jobs セクション自体が空と判定されます。

# NG: build: が jobs: の子ではなく孫になっている
jobs:
    build:
      steps:
        - run: npm test

# エラー
Invalid workflow file: .github/workflows/ci.yml#L1
  'on' is missing / 'jobs' is missing

# OK: jobs: の直下に1段だけインデントする(2スペース推奨)
jobs:
  build:
    steps:
      - run: npm test

GitHub Actions reports syntax problems as "Invalid workflow file" in the Actions tab before any job runs. Misaligned - under steps:, or an extra indentation level under jobs:, are the most common causes.

7. タブ文字を確実に見つける / Finding tabs reliably

タブとスペースは見た目が同じに見えるため、目視では気づけません。エディタで不可視文字を 表示する設定を入れておくと、次回以降のミスを未然に防げます。

• VS Code: 設定で "editor.renderWhitespace": "all" にすると、 スペースは ·、タブは → で表示される
• Vim: :set list でタブが ^I として可視化される
• JetBrains系(IntelliJ / PyCharm 等): 「表示 → アクティブエディターアクション → 空白文字を表示」

js-yaml(Node.js)でも同様にタブは拒否されます。

> require("js-yaml").load("key:\n\tvalue: 1\n")
YAMLException: bad indentation of a mapping entry (2:2)

Tabs and spaces are visually identical, so enable whitespace rendering in your editor (VS Code's editor.renderWhitespace, Vim's :set list) rather than relying on the eye. js-yaml raises the same class of indentation error when a tab appears where a mapping entry is expected.

8. docker-compose.yml の典型ミス / docker-compose pitfall

ports: の値をクォートせずに書くと、8080:80 のようなコロン付き文字列がYAMLのタイムスタンプ形式(sexagesimal)と誤解釈されることがあります。

# NG: クォートなしだと 8080:80 が数値として解釈される場合がある
services:
  web:
    ports:
      - 8080:80

# 実際に起きうる誤動作: "8080:80" が 60進数として計算され
# ports に意図しない整数値が渡り、Compose がエラーまたは異常なポート番号で失敗する

# OK: 文字列として明示的にクォートする
services:
  web:
    ports:
      - "8080:80"

Compose の公式ドキュメントでも ports や expose の値は クォートを推奨しています。数字とコロンだけの値は必ず文字列として扱われるよう クォートする習慣をつけてください。

An unquoted 8080:80 under ports: can be parsed as YAML's sexagesimal (base-60) number format instead of a string, producing an unexpected port value. Always quote colon-separated port mappings in docker-compose.yml.

まとめ / 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