できない.dev

Dockerfile の COPY でファイルが見つからずビルドできない

COPY のソースは Dockerfile があるディレクトリではなく build context 基準で解決される。
.dockerignore で除外されている、または build context 外を指していないか確認する。

公開: 更新:

症状できない · exit 1
docker build --progress=plain --no-cache -t copy-demo -f Dockerfile .
…
#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

2026-08-07 に github-actions-runner (host docker) で実際に打って取った出力。検証環境の詳細

要約

Dockerfile の COPY は build context (docker build の最後の引数で指定したディレクトリ)の配下しか参照できない。
failed to compute cache key: not found や COPY failed: file not found が出るときは、対象ファイルが context 外にあるか、.dockerignore で除外されていることがほとんどである。

実行例

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
$ echo $?
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 時点の出力

検証環境2026-08-07 検証
検証日
実行環境
github-actions-runner (host docker)

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

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 を使う)。

よくある原因

  1. build context の外を参照している。
    COPY ../shared/lib /app/lib のように一つ上の階層を指しているが、docker build . で context をカレントだけに絞っている。
  2. .dockerignore で除外している。
    node_modules を .dockerignore で無視しているのに、Dockerfile では COPY node_modules ./ と書いている。
  3. Dockerfile からの相対パスだと勘違いしている。
    「Dockerfile があるディレクトリからの相対パス」と思っているが、実際は build context ルートからの相対パスである。
  4. ファイル名の大文字小文字が違う。
    ファイル名 Config.json を config.json で COPY していると、macOS / Windows ではビルドが通り、Linux で落ちることがある。