T
yaml debugging configuration web-development devops

'YAML parse error' と一般的な YAML インデント問題の解決方法

'invalid YAML'、'YAML indentation error'、'YAML tab character' などのエラーを修正するための包括的なガイド。YAML の厳密な構文ルールを学びましょう。

2026-04-11

"YAML parse error" と一般的な YAML インデント問題の解決方法：完全ガイド

YAML (YAML Ain't Markup Language) は、人間が読みやすい形式とクリーンな構文で愛されています。Kubernetes、Docker Compose、GitHub Actions、および多くの静的サイトジェネレーターなどのツールにおける設定の標準となっています。しかし、YAML は空白とインデントに対して非常に厳格であることで知られています。一箇所でもスペースを間違えると、追跡が困難な invalid YAML や YAML parse error が発生する可能性があります。

このガイドでは、最も一般的な YAML エラーとその迅速な修正方法について説明します。

1. 一般的な YAML エラーメッセージ

使用しているパーサー（js-yaml や Python の PyYAML など）に応じて、以下のようなメッセージが表示される場合があります：

  • YAML parse error: bad indentation of a mapping entry (マッピングエントリの不適切なインデント)
  • YAML parse error: found character '\t' that cannot start any token (YAML tab character の混入)
  • invalid YAML: mapping values are not allowed here (マッピング値が許可されていない場所)
  • YAML parse error: duplicate key "..." (duplicate key in YAML / 重複したキー)
  • YAML syntax error: end of stream loss

2. 主な原因と解決策

2.1 インデントエラー (YAML indentation error)

YAML は、構造を定義するためにインデントを使用します（JSON の中括弧 {} のようなもの）。これは一貫性がなければなりません。

よくある間違い:

services:
  web:
    image: nginx
   ports:  # インデントが正しくない（2つまたは4つではなく3つのスペース）
      - "80:80"

解決策: マップまたはリスト内のすべての兄弟要素が、まったく同じ数の先行スペースを持っていることを確認してください。業界標準として 2 つのスペースを使用することをお勧めします。

2.2 タブ文字 (YAML tab character)

YAML はインデントにタブ文字 (\t) を使用することを厳格に禁止しています。必ずスペースを使用する必要があります。

エラーメッセージ: found character '\t' that cannot start any token

解決策: コードエディタ（VS Code、Sublime など）を「タブをスペースに変換」するように設定してください。すでにタブを含むコードを貼り付けてしまった場合は、「検索と置換」を使用して \t を に変換してください。

2.3 重複したキー (duplicate key in YAML)

他のいくつかの形式とは異なり、YAML ではマッピングの同じレベルに同じキーが 2 回表示されることは許可されていません。

よくある間違い:

image: nginx
ports:
  - "80:80"
image: alpine  # 重複したキー！

解決策: 特に大きなファイルや複数のファイルをマージする場合、誤ってキーが重複していないか設定を確認してください。

2.4 コロンの後のスペース不足

YAML でよくある落とし穴は、キーと値を区切るコロン (:) の後のスペースを忘れることです。

よくある間違い: url:https://example.com (YAML はこれを 1 つの長い文字列とみなします)

解決策: 常にスペースを含めてください: url: https://example.com。

2.5 複数行の文字列

長い文字列やコードブロックを含める必要がある場合は、正しいブロックスカラインジケーターを使用する必要があります: | (改行を保持) または > (改行を折り畳む)。

よくある間違い:

description: This is a
very long string
without indicators. # これは解析エラーを引き起こします

解決策:

description: |
  これは改行を
  保持する
  非常に長い文字列です。

3. 高度なトラブルシューティング

3.1 値の中の特殊文字

値に :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, ` などの文字が含まれている場合、パーサーが混乱することがあります。 解決策: 値全体を二重引用符 ("...") または一重引用符 ('...') で囲んでください。

3.2 boolean（真偽値）の落とし穴

YAML 1.1 では、yes、no、on、off などの値は自動的に boolean (true/false) に変換されます。文字列としての "no"（国コードなど）が必要な場合、これが原因で動作が壊れることがあります。 解決策: これらの文字列は常に引用符で囲んでください: country: "NO"。

4. 予防策とベストプラクティス

  1. YAML リンターを使用する: エディタにリンター（例: Red Hat の vscode-yaml）をインストールして、リアルタイムでエラーをキャッチします。
  2. スキーマ検証: Kubernetes や Docker Compose などの特定の形式については、公式の JSON/YAML スキーマを使用して検証します。
  3. 自動変換: JSON の方が使い慣れている場合は、設定を JSON で記述し、ツールを使用して YAML に変換します。
  4. 一貫したスペース: プロジェクト内のすべての YAML ファイルで 2 つのスペースを使用するように標準化します。

5. よくある質問 FAQ

Q: あるパーサーでは有効なのに、別のパーサーでは無効なのはなぜですか？

A: YAML には主に 1.1 と 1.2 の 2 つのバージョンがあります。一部のパーサー（PyYAML など）はデフォルトで 1.1 を使用しますが、他のパーサーは 1.2 を使用します。バージョン 1.2 は JSON との互換性が高くなっています。問題が発生した場合は、ファイルの先頭に %YAML 1.2 を追加してみてください。

Q: YAML でコメントは使えますか？

A: はい！ これは YAML が JSON に対して持つ大きな利点の 1 つです。# 記号を使用してコメントを記述できます。

Q: 一重引用符で囲まれた文字列の中で一重引用符をエスケープするにはどうすればよいですか？

A: YAML では、一重引用符を 2 回重ねることでエスケープします: 'It''s a beautiful day'。

6. クイックチェックツール

見えないタブ文字や間違ったスペースを見つけるのに苦労していませんか？当サイトの YAML 検証・整形ツール (YAML から JSON への変換と検証をサポート) をご利用ください。

  • 構文エラーをハイライト表示し、行番号を示します。
  • タブをスペースに自動的に変換します。
  • 乱雑な YAML を美しく整形し、可読性を向上させます。

関連するエラー

  • JSON の 'Unexpected token' エラーの解決方法
  • 'invalid base64 string' エラーの修正方法
  • 文字エンコーディングの不一致を理解する
ブログに戻る