YAMLのインデントエラーを原因別に直す手順

YAML で「インデントが不正」と言われたときは、まずエラー文の英語の一文を見てください。原因は 4 つほどしかなく、文面から機械的に引き当てられます。この記事では、その逆引き表と、エラーが出ないまま壊れる書き方の見つけ方をまとめます。

エラー文から原因を引く逆引き表

YAML を読むライブラリは言語ごとに違いますが、出るメッセージは似た言い回しに収束します。よく出る 6 つを並べます。

エラー文に出る言い回し	何が起きているか	まず試すこと
tab characters must not be used in indentation	行頭にタブが入っている	その行の行頭を半角スペースに打ち直す
bad indentation of a mapping entry	同じ階層のはずの行で先頭位置がずれている	前後の行と先頭位置を見比べる
bad indentation of a sequence entry	- の先頭位置がそろっていない	同じ並びの - を縦にそろえる
end of the stream or a document separator is expected	そこから先を読めていない	コロンの後ろに半角スペースがあるか見る
duplicated mapping key	同じ項目名が 2 回ある	後ろの値で上書きされている。片方を消す
could not find expected ':'	項目名と値の区切りが見つからない	全角コロン（：）を使っていないか見る

上の 3 つが「インデントエラー」と呼ばれるものです。下の 3 つは字下げと無関係ですが、字下げの崩れが原因で出ることがあるので一緒に載せています。

タブと全角スペースは、画面では探せない

インデントエラーの原因で多いのがこの 2 つです。どちらも見た目が半角スペースと変わらないため、目で探しても見つかりません。

タブ

タブは YAML の字下げとして認められていません。エディタの設定によって幅が 4 だったり 8 だったりするので、機械が「何段目か」を決められないためです。

エディタの「不可視文字を表示」を入れると、タブだけ矢印などの記号で見えるようになります。設定に「タブをスペースに変換」があれば、先にそれを入れておくのが早道です。

全角スペース

日本語入力のまま字下げすると入ります。こちらはタブと違い、エラーにならないことがあります。

字下げとして数えられるのは半角スペースだけなので、全角スペースは項目名の一部として読まれます。その結果、親にぶら下げたはずの項目が親から外れ、親のほうは中身が空になります。

エディタの検索窓に全角スペースを 1 つ打って検索すると、まとめて見つかります。置換で半角スペース 2 つに変えれば片が付きます。

階層のずれは「そろえる」と「深くする」で考える

先頭位置のずれは、2 つの規則だけで判断できます。

• 同じ階層の項目は、先頭位置を 1 文字もずらさずそろえる
• 子の項目だけを、半角スペースで深くする（幅は 2 でも 4 でもよいが、ファイル内で統一する）

崩れている例と直した例を並べます。

# 崩れている（3 行目だけ 1 文字深い）
server:
  host: example.com
   port: 443

# 直した
server:
  host: example.com
  port: 443

箇条書きの場合は - の位置をそろえます。- の中で項目を続けるときは、- の分だけ字下げが深くなる点に注意してください。

servers:
  - name: web
    port: 80
  - name: api
    port: 8080

name と port の先頭がそろっていることが大事です。port を name より浅くすると、別の項目として読まれます。

エラーが出ないまま壊れる書き方 3 つ

いちばん時間を取られるのは「エラーは出ないのに設定が効かない」ときです。原因はだいたい次の 3 つに絞られます。

1. 全角スペースの字下げ。前の節のとおり、読み取りは通ったまま親子関係だけが壊れます。

2. NO や yes が真偽値になる。引用符を付けずに書くと、読み込む側によっては false や true として扱われます。ノルウェーの国コード NO で実際に起きたことから NO 問題と呼ばれています。

国コード・郵便番号・バージョン番号は、引用符で囲むのが安全です。

3. 日付が日時に変わる。2026-08-25 のような書き方は、読み込む側が日付の型として解釈することがあります。文字列として扱ってほしいときは引用符で囲みます。

いずれも「読めているのに、読まれ方が違う」型の崩れです。エラーが出ないので、読み直した結果を自分の目で見る以外に確かめる方法がありません。

手元で確かめる

読み直した結果を見るには、YAML⇔JSON変換ツールに貼り付けて「YAML → JSON」を押してください。カッコの入れ子として結果が出るので、親子関係が意図どおりかを目で確かめられます。

このツールは、全角スペースの字下げ・タブ・全角コロン・コロン後の空白抜けを、変換の前に行番号つきで指摘します。読み取りに失敗したときの理由と直し方も日本語で出ます。操作の手順はYAMLとJSONを相互変換して中身を確かめる手順にまとめています。

それでも直らないときの確認順

ここまでで直らない場合は、次の順に見ていくと切り分けられます。

1. 指された行の 1 つ上の行を見る。前の行が閉じきっていないことが多くあります。
2. ファイル全体をタブと全角スペースで検索する。1 か所でも残っていれば疑います。
3. 字下げの幅がファイル内で混ざっていないか見る。2 と 4 が混在すると、人の目には整って見えても機械は別の階層と読みます。
4. 怪しい部分だけを別のファイルに切り出す。10 行に減らすと原因の行が浮かびます。
5. 引用符で囲んでみる。値の書き方が原因なら、囲むだけで通ります。

関連ツール

• YAML⇔JSON変換 — 読み直した結果を目で確かめたいとき
• JSON整形ツール — JSON 側のエラー位置を知りたいとき
• 全角⇔半角変換 — 全角の記号が混ざったテキストを直したいとき

関連記事

• YAMLとJSONを相互変換して中身を確かめる手順
• JSONのエラーが出たときに整形して読みやすくするコツ

まとめ

インデントエラーは、エラー文の英語を逆引き表に当てれば原因まで一気に絞れます。タブと全角スペースは目で探さず、検索で見つけてください。

エラーが出ないまま壊れる書き方には、読み直した結果を見る以外の確かめ方がありません。設定を反映する前に一度通しておくと、後で戻る手間がなくなります。