Dockerfile の COPY でファイルが見つからずビルドできない
COPY のソースは Dockerfile があるディレクトリではなく build context 基準で解決される。
.dockerignore で除外されている、または build context 外を指していないか確認する。
公開: 更新:
要約
Dockerfile の COPY は build context （docker build の最後の引数で指定したディレクトリ）の配下しか参照できない。failed to compute cache key: not found や COPY failed: file not found が出るときは、対象ファイルが context 外、もしくは .dockerignore で除外されていることがほとんど。
よくある原因
- build context 外を参照している:
COPY ../shared/lib /app/libのように一つ上の階層を指しているが、docker build .で context をカレントだけに絞っている。 - .dockerignore で除外:
node_modulesを.dockerignoreで無視しているのに、Dockerfile ではCOPY node_modules ./と書いている。 - Dockerfile 相対と勘違い: 「Dockerfile があるディレクトリからの相対パス」と思っているが、実際は build context ルートからの相対。
- 大文字小文字の差: ファイル名
Config.jsonをconfig.jsonで COPY しているが macOS / Windows ではビルドが通り Linux で落ちる、など。
解決策
1. build context を確認する
docker build -f path/to/Dockerfile . の . の部分が context。
BuildKit は最初に context を tar で収集する。
docker build -t myapp -f docker/Dockerfile .context 内に対象ファイルがあるかは次のコマンドで簡易確認できる。
find . -name "needed-file" 2>/dev/null | head公式ドキュメント（新しいタブで開く） のとおり、context 外への参照は許されない。
2. .dockerignore を疑う
意図せず除外されていないか調べる。
mv .dockerignore .dockerignore.bak
docker build -t myapp .通れば .dockerignore の特定行が原因。
マッチング書式は .gitignore と同様だが、否定パターンの挙動は微妙に異なるので 1 行ずつ確認する。
3. context を広げて Dockerfile を書き直す
親階層の共通ライブラリを参照したい場合、context をプロジェクトルートに広げて Dockerfile 側のパスを書き直す。
project/
├── docker/Dockerfile
├── shared/lib/
└── app/# docker/Dockerfile
COPY shared/lib /app/lib
COPY app /appビルドは docker build -f docker/Dockerfile .（プロジェクトルートで実行）。
4. 環境差をなくす
CI が Linux のときはローカル macOS と挙動が違う。COPY のパスは小文字で揃え、ファイル名のリネームを Git で確実に追跡する（git mv を使う）。
実行例
実際に上記の手順を GitHub Actions Runner（Ubuntu 24.04.4 LTS、Docker 28.0.4）で動かすと、COPY ../shared/lib /app/lib の一段上を参照するケースでは failed to compute cache key: "/shared/lib": not found が発生し、続いて context をプロジェクトルートに広げて docker build -f docker/Dockerfile . で再実行すると COPY shared/lib および COPY app /app/app がいずれも成功し、終了コード 0 でイメージが生成された。
検証環境のバージョンは実行ログの冒頭に次のとおり記録されている。
PRETTY_NAME="Ubuntu 24.04.4 LTS"
Docker version 28.0.4, build b8034c0$ docker build --progress=plain --no-cache -t copy-demo -f Dockerfile .
#0 building with "default" instance using docker driver
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 79B done
#1 DONE 0.0s
#2 [internal] load metadata for docker.io/library/alpine:3
#2 ...
#3 [auth] library/alpine:pull token for registry-1.docker.io
#3 DONE 0.0s
#2 [internal] load metadata for docker.io/library/alpine:3
#2 DONE 1.0s
#4 [internal] load .dockerignore
#4 transferring context: 2B done
#4 DONE 0.0s
#5 [internal] load build context
#5 transferring context: 2B done
#5 DONE 0.0s
#6 [2/2] COPY ../shared/lib /app/lib
#6 ERROR: failed to calculate checksum of ref dce1e4a9-fc26-4218-aaf0-feee5194c8cb::z4pvih1wnw5wguuyeopgeqflm: "/shared/lib": not found
#7 [1/2] FROM docker.io/library/alpine:3@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b
#7 resolve docker.io/library/alpine:3@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b done
#7 sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b 9.22kB / 9.22kB done
#7 DONE 0.0s
------
> [2/2] COPY ../shared/lib /app/lib:
------
Dockerfile:2
--------------------
1 | FROM alpine:3
2 | >>> COPY ../shared/lib /app/lib
3 |
--------------------
ERROR: failed to build: failed to solve: failed to compute cache key: failed to calculate checksum of ref dce1e4a9-fc26-4218-aaf0-feee5194c8cb::z4pvih1wnw5wguuyeopgeqflm: "/shared/lib": not found
build の終了コード: 1$ cat docker/Dockerfile
FROM alpine:3
COPY shared/lib /app/lib
COPY app /app/app
RUN ls -R /app再現に使った Dockerfile は解決策 3 の例と宛先が異なり COPY app /app/app としている。
解決策 3 の COPY app /app でも、context がプロジェクトルートであれば同じく成功する。
ここで確かめたいのは宛先パスではなく context の位置である。
$ docker build --progress=plain --no-cache -t copy-demo -f docker/Dockerfile .
#0 building with "default" instance using docker driver
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 109B done
#1 DONE 0.0s
#2 [internal] load metadata for docker.io/library/alpine:3
#2 DONE 0.1s
#3 [internal] load .dockerignore
#3 transferring context: 2B done
#3 DONE 0.0s
#4 [1/4] FROM docker.io/library/alpine:3@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b
#4 CACHED
#5 [internal] load build context
#5 transferring context: 186B done
#5 DONE 0.0s
#6 [2/4] COPY shared/lib /app/lib
#6 DONE 0.7s
#7 [3/4] COPY app /app/app
#7 DONE 0.0s
#8 [4/4] RUN ls -R /app
#8 0.218 /app:
#8 0.218 app
#8 0.218 lib
#8 0.218
#8 0.218 /app/app:
#8 0.218 main.txt
#8 0.218
#8 0.218 /app/lib:
#8 0.218 util.txt
#8 DONE 0.2s
...（以降の export 処理は省略）— 2026-08-07 時点の出力