「contained only whitespace」エラーの対処 — Claude Code非対話モード
空白だけのプロンプトはAPIに送られる前にClaude Codeが拒否します。-pとstream-jsonセッションで挙動が違う理由と、スクリプト側の対処をまとめました。
Input contained only whitespaceが出る条件
非対話モード(claude -p)でスペースや改行だけのプロンプトを渡すと、モデルに送信される前にClaude Codeが処理を止めます。プロンプト引数か標準入力で -p にテキストを渡す形では、次のエラーで終了します。
Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print--input-format stream-json で動かしている実行中セッションやAgent SDKのセッションに空白だけのメッセージを送った場合は、エラーで終了せずセッションはそのまま使える状態を保ちます。代わりに、モデルを呼び出さずにターンを終え、案内メッセージとターンの結果テキストの両方に次の文言が入ります。
Blank prompt — the message was only whitespace, so nothing was sent to the model.同じ「空白だけの入力」が原因でも、単発の -p 実行かストリーミング中のセッションかで表面化の仕方が違います。
エラーの意味 — Claude API自体が可視文字のないメッセージを拒否する
Claude Codeがこの入力を送信前に止めているのは、Claude APIが可視文字を含まないメッセージを受け付けない仕様のためです。空白だけのメッセージをそのまま送っても、APIから拒否されるだけで意味のある応答は返りません。Claude Code側で事前に弾くことで、モデルへのリクエスト自体が発生しません。
直し方
単発のclaude -p実行で出た場合
プロンプトに可視のテキストを含めるだけです。引数を渡す場合、クオートの位置がずれて空文字列や空白だけになっていないかを確認します。
claude -p "現在のブランチの差分を要約して"パイプで渡している場合は、パイプの手前で中身が空になっていないかを先に確認します。
echo "現在のブランチの差分を要約して" | claude -pシェルスクリプトから変数や外部ファイルでプロンプトを組み立てている場合
このエラーが実運用で厄介なのは、CIジョブやラッパースクリプトが変数やファイルからプロンプトを組み立てているケースです。変数が意図せず空になっていたり、テンプレートの置換に失敗して空白しか残らなかったりすると、claude を呼び出した時点で初めて発覚します。呼び出し前に中身を検証しておくと、失敗の原因がスクリプト側かClaude Code側かをその場で切り分けられます。
PROMPT="$(cat prompt.txt)"
if [ -z "$(echo "$PROMPT" | tr -d '[:space:]')" ]; then
echo "prompt.txtの中身が空です" >&2
exit 1
fi
claude -p "$PROMPT"tr -d '[:space:]' で空白文字をすべて除去した結果が空文字列かどうかを見れば、改行やタブだけが残っているケースも含めて検出できます。
CI・ラッパースクリプトの事前検証は3ケースに分けて書く
上のチェックを実運用のスクリプトに組み込むときは、想定される失敗パターンを1つの条件式で済ませず、原因ごとに分けて書いておくと後で調査しやすくなります。想定すべきケースは大きく3つです。
- 変数がそもそも未設定・空文字列:
PROMPT=""のまま呼び出してしまうケース。[ -z "$PROMPT" ]で単独に検出できます。 - 変数に改行やタブだけが残っている: テンプレートエンジンの出力が空行だけになっている場合など。
tr -d '[:space:]'を通した後に空文字列かどうかを見ないと検出できません。 - 可視文字はあるが実質的に無意味な値が入っている: プレースホルダー文字列(
{{PROMPT}}が未置換のまま残るなど)がそのまま渡るケースです。これは「空白だけの入力」エラーにはならず正常に送信されてしまうため、別途プレースホルダー文字列の残存チェックを足す必要があります。
1と2は本記事の「Input contained only whitespace」または「Input must be provided」で機械的に検出できますが、3はClaude Code側では検出されないため、呼び出し元のスクリプトで個別に対処するしかありません。
stream-jsonセッションやAgent SDKの中で出た場合
対処は不要なことがほとんどです。このケースではセッションが終了せず、次のメッセージを送れば通常どおり続行できます。ただし、案内メッセージを見逃すとClaudeが応答していないように見えてしまうため、--include-partial-messages や結果テキストを監視している自動化フローでは、このメッセージが来たらメッセージ生成側の不具合を疑う分岐を用意しておくと原因追跡が早まります。Agent SDKでユーザー入力をそのまま転送している構成では、入力欄の前後の空白をトリムしてから送る実装にしておくと、この分岐に入る頻度自体を減らせます。
自動送信ツールで「本当に空白しか送っていないか」を確かめたいときは、--input-format stream-json --output-format stream-json に --replay-user-messages を加えて実行します。このフラグは受け取ったユーザーメッセージを標準出力にそのまま再送出するため、送信側のログと突き合わせれば、途中の変換処理で本文が失われて空白だけになっていないかを切り分けられます。
Blank prompt検出時の自動化フロー分岐
監視スクリプト側で Blank prompt の案内メッセージを検出したときの分岐は、次の3段階で組んでおくと運用しやすくなります。
- 検出: 結果テキストまたは案内メッセージに
Blank promptの文言が含まれるかを監視する。 - 記録: どのターンで発生したか、直前に送信しようとしたメッセージの生成元(テンプレート、外部API、ユーザー入力欄のいずれか)をログに残す。
- 再送または停止: メッセージ生成側の不具合が一時的なもの(外部APIのタイムアウトなど)であればリトライし、恒常的な不具合(テンプレートの参照先が存在しないなど)であれば自動化フローを止めて人間に通知する。
セッション自体はエラーで終了しないため、3の分岐を用意しておかないと、空白メッセージが繰り返し送られ続けているのに自動化フローだけが正常終了したように見えるという状態に陥りがちです。
隣接するエラー: Input must be providedとの違い
似た場面で出る別のエラーに「Input must be provided either through stdin or as a prompt argument when using --print」があります。この記事のエラーとは原因が違うので混同しないでください。
| エラー文言 | 原因 |
|---|---|
Input contained only whitespace | 原因プロンプトの中身が空白文字だけ(何かは渡っている) |
Input must be provided... | 原因プロンプトが何も渡っていない(引数なし・標準入力もパイプされていない) |
Input must be providedが出る再現条件
後者は、標準出力がターミナルでない環境(リダイレクトされたコンソールやPowerShell ISEなど)で claude を引数なしで実行したときにも出ます。この場合Claude Codeは対話UIを起動できないため非対話モードとして動作しようとし、-p を指定していなくてもメッセージに --print の名前が出ます。渡した覚えのないプロンプトが必要だと言われて戸惑ったら、まずこのケースに該当していないかを疑ってください。
再現条件は次の2パターンです。
- 標準入力がパイプされておらず、プロンプト引数も渡していない:
claudeだけを実行した場合。対話UIが起動できる環境ならそのまま対話モードに入りますが、起動できない環境では非対話モードとして扱われ、プロンプトが無いためこのエラーになります。 -pを指定したが引数もパイプもない:claude -pとだけ実行し、標準入力に何も流し込んでいない場合。明示的に非対話モードを指定しているため、プロンプトが無いことがすぐにエラーとして表面化します。
よくある質問
改行だけのプロンプトも空白扱いになるか
なります。判定対象はスペース・タブ・改行のいずれかで構成された文字列で、可視文字が1つも無ければ空白だけとみなされます。見た目上何も入力していないように見えても、実際には改行コードだけが残っているケースがこれに当たります。
空白の前後に本文がある場合は問題ないか
問題ありません。判定は「メッセージ全体が空白だけかどうか」であり、可視文字が1文字でも含まれていれば通常どおり送信されます。前後の余分な空白を気にする必要はなく、トリムするかどうかは任意です。
このエラーはAPIの利用料金に影響するか
このエラーで止まった呼び出し自体は、モデルへのリクエスト自体が発生していません。v2.1.229より前の挙動(APIへ送信してから400エラーを受け取る形)では、リクエストはAPI側で400エラーとして拒否されます。
stream-jsonセッションでこのメッセージが出たあと、履歴はどうなるか
ターンとして記録されますが、モデルへの呼び出しは発生しません。
空文字列を渡した場合も同じエラーになるか
なりません。claude -p "" のように完全な空文字列を渡すと、Claude Codeはプロンプトそのものが渡っていないと判断し、「Input must be provided」のエラーになります。一方 claude -p " " のようにスペース1文字でも渡していれば、プロンプト自体は受け取ったうえで中身が空白だけだと判定され、本記事の「Input contained only whitespace」になります。どちらのエラーが出たかを見れば、呼び出し元のスクリプトが引数を渡し忘れているのか、空白だけの値を生成してしまっているのかを区別できます。
関連して確認したい設定
--bg と --print の併用エラーなど、非対話モードのフラグ周りでつまずきやすい点は--bgと--printの競合エラーの解決法にまとめています。CI環境から claude -p を呼び出す全体の構成はClaude CodeをGitHub Actionsに組み込む、Agent SDKでの最小実装はClaude Agent SDK入門を参考にしてください。