Dockerエラー解決：failed to compute cache key not found の修正方法

クイック解決：要約

このエラーは通常、Docker BuildKitが COPY または ADD 命令で指定されたファイルやディレクトリを見つけられないことを意味します。多くの場合、次の3つのチェックで解決します：

ビルドコンテキスト： 正しいディレクトリから docker build コマンドを実行していますか？通常、これはプロジェクトのルートディレクトリです。
パスの正確性： Dockerfile 内のソースパスは、ビルドを開始した場所からの相対パスとして存在していますか？
.dockerignore： コピーしようとしているファイルが、誤って .dockerignore のルールによってブロックされていませんか？

発生原因

BuildKitは各レイヤーに対して一意のキャッシュキーを生成します。COPY コマンドが実行されると、「ビルドコンテキスト」（コマンドの最後で指定する . などのディレクトリパス）をスキャンします。Dockerに COPY config.json . と指示しても、そのコンテキストフォルダ内に config.json が存在しない場合、BuildKitは即座に「not found」エラーで停止します。

failed to solve: rpc error: code = Unknown desc = failed to compute cache key: "/config.json" not found: not found

よくある主な原因

1. 誤ったビルドコンテキスト

コンテキストのエラーは、開発者がサブディレクトリからビルドを実行したときに最も多く発生します。次のようなプロジェクト構造を想定してみましょう：

my-project/
├── app/
│   ├── main.py
│   └── Dockerfile
└── requirements.txt

cd app を実行してから docker build -t my-app . を実行すると、Dockerは app/ フォルダ内のファイルしか認識しません。requirements.txt は1つ上の階層にあるため、COPY requirements.txt . コマンドは失敗します。これを解決するには、代わりにルートディレクトリからビルドを実行します：

# my-project/ から実行
docker build -t my-app -f app/Dockerfile .

2. 過剰な .dockerignore のルール

.dockerignore ファイルは、サイズの大きいファイルや機密ファイルが Docker デーモンに送信されるのを防ぎます。しかし、*.json や dist/ のような広範なワイルドカードを指定すると、イメージに必要なファイルまでブロックしてしまう可能性があります。ファイルが無視（ignore）されている場合、BuildKitにとっては存在しないものとして扱われます。

解決策： .dockerignore のパターンを見直してください。無視パターンに一致する特定のファイルを含める必要がある場合は、例外を示す ! プレフィックスを使用します：

# すべてのJSONファイルを無視...
*.json
# ...ただし、アプリに必要なファイルは除く
!important-config.json

3. 大文字小文字の区別の競合

Windows や macOS のファイルシステムは一般的に大文字小文字を区別しませんが、Docker コンテナが動作する Linux は厳密に区別します。実際のファイル名が App.js なのに、Dockerfile で COPY app.js . と記述していると失敗します。開発中のローカルマシンでは動作しても、Linux 上で動作する CI/CD パイプラインではエラーになる可能性が高いです。

解決策： ファイル名を確認してください。Dockerfile 内の記述がディスク上のファイル名と大文字小文字まで正確に一致しているか確認します。

4. ソースパスの先頭のスラッシュ

COPY や ADD におけるソースパスは、ビルドコンテキストからの相対パスである必要があります。先頭にスラッシュを追加すると検索動作が変わり、多くの場合エラーの原因となります。

# 誤り：システムルートの /src を検索する
COPY /src ./src

# 正解：プロジェクトフォルダ内の src を検索する
COPY src ./src

コンテキストのデバッグ方法

解決しない場合は、「デバッグ用」ビルドを使用して、Dockerが実際に何を認識しているかを確認してください。これには30秒ほどしかかからず、推測に頼る必要がなくなります。

debug.Dockerfile を作成します：

FROM alpine
WORKDIR /check
COPY . .
CMD ls -R

ビルドを実行して出力を確認します：

docker build -t build-debug -f debug.Dockerfile .
docker run --rm build-debug

ls -R でファイルが表示されない場合、そのフォルダにファイルが存在しないか、.dockerignore によって除外されています。

ベストプラクティス

ルートの標準化： パスの予測可能性を保つため、常にプロジェクトのルートからビルドを実行しましょう。
コンテキストサイズの制限： コンテキストフォルダが大きすぎると（例：500MB以上）、ビルドが遅くなります。node_modules や .git には .dockerignore を活用しましょう。
相対パスの使用： ソースファイルに対して絶対パスや先頭のスラッシュを使用しないでください。
大文字小文字の一致： クロスプラットフォームでのトラブルを避けるため、ファイル名は小文字に統一するのが無難です。