title: “Docker マルチステージビルドで COPY に失敗する・ファイルが見つからない” date: 2026-01-16 draft: true description: “Docker マルチステージビルドで COPY –from でファイルが見つからない、No such file or directory エラーの確認手順と対処法” categories: [“runbook”] tags: [“runbook”, “docker”, “マルチステージビルド”, “COPY”, “file not found”, “ビルドエラー”]

症状

Docker マルチステージビルドで COPY --from=<stage> を実行すると「file not found」「No such file or directory」エラーが発生する。

結論：まずこれを確認

  1. COPY 元のステージ名（または番号）が正しいか確認する
  2. COPY 元のパスが、前のステージでの実際の出力先と一致しているか確認する
  3. 前のステージのビルドが成功しているか確認する

トラブルシューティングフロー

    flowchart TD
    A[COPY --from でエラー] --> B{ステージ名/番号は正しい?}
    B -->|No| C[ステージ名を修正]
    B -->|Yes| D{前ステージのビルドは成功?}
    D -->|No| E[前ステージのエラーを解決]
    D -->|Yes| F{COPY元パスは正しい?}
    F -->|No| G[パスを修正]
    F -->|Yes| H{ファイルは実際に存在?}
    H -->|No| I[前ステージの出力先を確認]
    H -->|Yes| J[パーミッションを確認]

よくある原因

  • ステージ名のタイプミス - AS builder と --from=build のように名前が一致していない
  • ステージ番号の間違い - --from=0 など番号指定で、順番を誤認している
  • パスの指定ミス - 前ステージでの出力先と COPY 元のパスが異なる
  • 前ステージでファイルが生成されていない - ビルドコマンドが失敗している、または出力先が違う
  • 相対パス・絶対パスの混同 - WORKDIR の影響でパスがずれている
  • ビルドキャッシュの影響 - 古いキャッシュで不整合が発生している
  • .dockerignore による除外 - 必要なファイルが除外されている（初回 COPY 時）

確認手順

ステップ1: Dockerfile のステージ名を確認する

    grep -n "^FROM\|AS " Dockerfile

🔍 チェックポイント: FROM ... AS <name> の <name> が COPY --from=<name> と一致しているか

出力例：

    1:FROM node:20 AS builder
15:FROM node:20-slim AS runner

この場合、COPY --from=builder が正しい。COPY --from=build はエラーになる。

ステップ2: 前ステージの出力先を確認する

Dockerfile 内で、前ステージがどこにファイルを出力しているか確認する。

    grep -n "WORKDIR\|COPY\|RUN.*build\|RUN.*install" Dockerfile

🔍 チェックポイント: WORKDIR と実際の出力パスの組み合わせを確認

例：WORKDIR が /app で npm run build を実行すると、出力は /app/dist などになる。

ステップ3: 前ステージのみをビルドして中身を確認する

    docker build --target builder -t debug-stage .
docker run --rm debug-stage ls -la /app/dist

🔍 チェックポイント: 期待するファイルが期待するパスに存在するか

    # ファイルが存在しない場合、どこにあるか探す
docker run --rm debug-stage find / -name "*.js" 2>/dev/null | head -20

ステップ4: キャッシュを無効にしてビルドする

    docker build --no-cache -t myapp .

🔍 チェックポイント: キャッシュなしで同じエラーが出るか

ステップ5: .dockerignore を確認する

    cat .dockerignore

🔍 チェックポイント: 必要なファイルやディレクトリが除外されていないか

NG行動（やってはいけないこと）

  • エラーを見ずに COPY 行だけ修正する - 前ステージの問題を見落とす
  • ステージ番号（0, 1, 2…）で指定する - 名前を使う方が保守性が高い
  • 全ファイルをコピーする COPY --from=builder / / - 不要なファイルが含まれ、イメージサイズが増大する
  • デバッグ用の変更を本番 Dockerfile にそのまま残す - セキュリティリスクになる

よくある質問（FAQ）

Q1: COPY --from=0 のような番号指定は使える？

A: 使える。0 は最初の FROM ステージを指す。ただし、ステージの順序変更時にエラーの原因になるため、AS <name> で名前を付けて --from=<name> を使うことを推奨。

Q2: 外部イメージから COPY できる？

A: 可能。COPY --from=nginx:latest /etc/nginx/nginx.conf /etc/nginx/ のように、イメージ名を直接指定できる。

Q3: 複数ファイルを一度に COPY するとエラーになる

A: COPY 先をディレクトリにする場合は末尾に / を付ける。COPY --from=builder /app/dist/* /app/ のように指定する。

関連するエラー・症状

解決しない場合

公式ドキュメント

確認すべきログ・情報

  • docker build の全出力（--progress=plain オプションで詳細表示）
  • 前ステージの RUN コマンドの出力

次に調べるキーワード

  • docker multi-stage build COPY failed
  • docker --from stage not found
  • dockerfile COPY no such file or directory