こんにちは、かつコーチです。
Dockerを使い始めると、必ずと言っていいほど何かしらのエラーメッセージにぶつかります。
英語の長いエラー文を見て「何をどう直せばいいのか分からない」と手が止まってしまう方も多いのではないでしょうか。
この記事では、筆者がこれまで実際に遭遇したものを中心に、Dockerでよく出会うエラーを「起動時」「ビルド時」「接続時」の3つの場面に分けてまとめます。
エラーメッセージの読み方のコツも合わせて紹介するので、これから同じエラーに出会ったときの引き出しにしてください。
Dockerでよくあるエラーの全体像
エラーが起きやすい3つの場面
Dockerのエラーは、発生するタイミングによって原因がある程度絞り込めます。
| 場面 | 起きやすい原因 |
|---|---|
| コンテナ起動時 | ポートの競合、ファイル・パスの指定ミス |
| イメージビルド時 | COPY対象ファイルの不足、ビルドコンテキストの誤り |
| コンテナ間通信時 | 起動タイミングのズレ、ネットワーク設定の誤り |
エラー文の中に「port」「build」「connect」といったキーワードが含まれていないか探すと、どの場面のエラーかを素早く判断できます。
まずは焦らず、エラーメッセージ全体を上から下まで読む癖をつけましょう。
多くの場合、最後の1〜2行に具体的な原因が書かれています。
コンテナ起動時によくあるエラー
port is already allocated
コンテナ起動時に最も遭遇しやすいのが、ポート競合のエラーです。
筆者が実際にdocker run -p 3306:3306 mysqlを実行した際、以下のエラーが出ました。
Error response from daemon: driver failed programming external connectivity on endpoint mysql-container: Bind for 0.0.0.0:3306 failed: port is already allocated
これは、ホスト側の3306番ポートを別のプロセス（すでに起動しているMySQLなど）がすでに使っている状態で起きるエラーです。
❌ Before（競合するポートをそのまま指定）
docker run -d -p 3306:3306 mysql
✅ After（ホスト側のポート番号を変更）
docker run -d -p 3307:3306 mysql
ホスト側のポート番号（-pの左側）を、まだ使われていない番号に変更すれば解決します。
どのプロセスがポートを使っているか調べたい場合は、lsof -i :3306（Mac/Linux）で確認できます。
no such file or directory
コンテナ起動時に、指定したファイルパスが見つからないというエラーもよく発生します。
docker: Error response from daemon: OCI runtime create failed: ... exec: "npm": executable file not found in $PATH: unknown.
このエラーは、コンテナ内に実行しようとしたコマンド（この例ではnpm）が存在しないことを示しています。
ベースイメージにnodeではなくnode:alpineのような軽量版を使った際、必要なパッケージが含まれていないケースなどで起こりやすいエラーです。
Dockerfileのベースイメージを見直すか、必要なパッケージをRUN apt-get installなどで追加インストールしましょう。
イメージビルド時によくあるエラー
COPY failed: file not found
DockerfileのCOPY命令で、存在しないファイルを指定するとビルドが失敗します。
筆者がpackage.jsonをリポジトリのルートではなくsrc/配下に置いていたのに気づかず、以下のエラーに遭遇したことがあります。
failed to solve: failed to compute cache key: failed to calculate checksum of ref: "/package.json": not found
❌ Before（ファイルの実際の場所を確認せずCOPY）
COPY package.json .
✅ After（ビルドコンテキスト内の正しいパスを指定）
COPY src/package.json .
このエラーが出たら、まずビルドコンテキスト（docker build .の.で指定したディレクトリ）を基準に、指定したファイルが本当にその場所にあるかを確認してください。
.dockerignoreでそのファイルが除外対象になっていないかも合わせてチェックすると原因を特定しやすくなります。
キャッシュがらみのビルド失敗
RUN命令を変更したのにビルド結果が反映されない、という相談もよく受けます。
Dockerは各命令をレイヤーごとにキャッシュするため、途中の命令に変更がないと過去のキャッシュがそのまま使われることがあります。
キャッシュを無視して強制的にビルドし直したい場合は、以下のオプションを使います。
docker build --no-cache -t my-app .
普段は高速化に役立つキャッシュ機能ですが、「なぜか変更が反映されない」ときの原因候補として覚えておきましょう。
コンテナ間通信・接続エラー
connection refused
Web用コンテナからDB用コンテナに接続しようとして失敗するのも、初心者がよくつまずくポイントです。
psql: error: connection to server at "db", port 5432 failed: Connection refused
Is the server running on that host and accepting TCP/IP connections?
このエラーの多くは、DBコンテナの起動が完了する前にWebコンテナが接続を試みてしまうタイミングのズレが原因です。
コンテナが「起動した」ことと、中のアプリが「接続を受け付けられる状態になった」ことは、必ずしもイコールではありません。
この待ち時間の制御方法は、docker-composeのhealthcheck機能を使う実践的な解決策も含めて、次回以降の記事で詳しく扱います。
まずは「コンテナは起動直後、少し待たないと接続できないことがある」と覚えておくだけでも、原因の切り分けが早くなります。
まとめ
この記事のポイント
- Dockerのエラーは「起動時」「ビルド時」「接続時」の3場面でだいたい分類できる
- ポート競合は
-pのホスト側ポート番号を変更すれば解決できることが多い - ビルドエラーはビルドコンテキストとファイルパスのズレを疑う
- 接続エラーはコンテナの起動完了タイミングのズレが原因になりやすい
次に読むべき記事
- docker-composeとは？複数コンテナをまとめて管理する
- docker-composeでWeb+DB構成を連携させる
- Dockerネットワークの基本：コンテナ同士をつなぐ
タグ: Docker, 初心者向け, エラー解決