Docker Runbook

症状 docker build 実行時に no space left on device エラーが表示され、ビルドが失敗する。 結論：まずこれを確認 docker system df でDockerが使用している容量を確認 docker system prune -a で不要なリソースを削除 それでも解決しない場合は /var/lib/docker のディスク容量を確認 トラブルシューティングフロー flowchart TD A[no space left on device] --> B{docker system df を確認} B -->|使用量が多い| C[docker system prune を実行] B -->|使用量が少ない| D[ホストのディスク容量を確認] C --> E{解決した?} E -->|Yes| F[完了] E -->|No| G[ビルドキャッシュを削除] G --> H{解決した?} H -->|Yes| F H -->|No| D D --> I{空き容量あり?} I -->|No| J[不要ファイルを削除/ディスク拡張] I -->|Yes| K[Docker data-root を確認] よくある原因 未使用イメージの蓄積 - 古いイメージが削除されずに残っている ビルドキャッシュの肥大化 - 中間レイヤーがキャッシュとして大量に残っている 停止コンテナの残存 - 停止したコンテナがディスクを消費し続けている 未使用ボリュームの蓄積 - データボリュームが削除されずに残っている ホストディスクの容量不足 - Docker以外のファイルでディスクが圧迫されている Docker data-root の設定ミス - 容量の少ないパーティションにDockerデータが配置されている マルチステージビルドの中間イメージ - ビルド途中のイメージがキャッシュに残っている 確認手順 ステップ1: Dockerのディスク使用状況を確認する docker system df 🔍 チェックポイント: RECLAIMABLE の値が大きければ、削除可能なリソースが多い ...

症状 docker exec コマンド実行時に Error: No such container: コンテナ名 が表示される。 結論：まずこれを確認 docker ps -a でコンテナの存在と状態を確認する コンテナ名・IDのタイプミスがないか確認する コンテナが Exited 状態なら docker start で起動する トラブルシューティングフロー flowchart TD A[No such container エラー] --> B{docker ps -a で<br>コンテナが表示される?} B -->|No| C[コンテナが存在しない] B -->|Yes| D{STATUSは<br>Up?} C --> C1[コンテナ名/IDを再確認] C1 --> C2[docker run で作成が必要] D -->|No| E[コンテナが停止中] D -->|Yes| F{コンテナ名/IDは<br>正確?} E --> E1[docker start で起動] F -->|No| G[名前/IDを修正して再実行] F -->|Yes| H[Docker デーモン再起動を検討] よくある原因 コンテナ名・IDのタイプミス - 大文字小文字、ハイフン、アンダースコアの違い コンテナが停止している - Exited 状態のコンテナには exec できない コンテナが削除されている - docker rm や --rm オプションで削除済み 別の Docker コンテキストを参照 - Docker Desktop と CLI で異なる環境を見ている コンテナ名の重複回避で別名になっている - docker-compose が自動でサフィックスを付与 docker-compose のプロジェクト名が異なる - ディレクトリ名がプレフィックスになる 確認手順 ステップ1: 全コンテナの一覧を確認する docker ps -a 🔍 チェックポイント: 対象のコンテナが一覧に表示されるか確認する。表示されなければコンテナは存在しない。 ...

症状 docker logs <container> を実行してもログが表示されない、または空の出力になる。 結論：まずこれを確認 アプリケーションが stdout/stderr に出力しているか確認する ログドライバーが json-file または journald になっているか確認する コンテナが実際に起動して動作しているか確認する トラブルシューティングフロー flowchart TD A[docker logs が空] --> B{コンテナは起動している?} B -->|No| C[docker ps -a で状態確認] B -->|Yes| D{ログドライバーは json-file?} D -->|No| E[ログドライバーを確認] D -->|Yes| F{アプリは stdout に出力?} F -->|No| G[アプリのログ設定を確認] F -->|Yes| H{ログローテーションで消えた?} H -->|Yes| I[ログ設定を見直す] H -->|No| J[docker inspect で詳細確認] C --> K[コンテナを起動/再作成] E --> L[対応ドライバーに変更] G --> M[stdout/stderr に出力するよう修正] よくある原因 アプリケーションがファイルにログを出力している - stdout/stderr ではなく /var/log/ などに書いている ログドライバーが none に設定されている - ログが一切保存されない設定 ログドライバーが syslog や fluentd など外部送信型 - docker logs では取得できない アプリケーションがバッファリングしている - Python など一部言語でバッファが溜まるまで出力されない コンテナがすぐに終了している - 起動直後にクラッシュしてログが残らない ログローテーションで古いログが削除された - max-size / max-file 設定による コンテナを --rm で起動して削除済み - コンテナ削除と同時にログも消える 確認手順 ステップ1: コンテナの状態を確認する docker ps -a --filter "name=対象コンテナ名" 🔍 チェックポイント: STATUS が Up になっているか、Exited の場合は終了コードを確認 ...

症状 docker pull 実行時に以下のいずれかのエラーが表示される： Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers) Error response from daemon: Get "https://registry-1.docker.io/v2/": dial tcp: lookup registry-1.docker.io: connection refused 結論：まずこれを確認 curl -I https://registry-1.docker.io/v2/ で Docker Hub への疎通を確認 プロキシ環境なら Docker デーモンにプロキシ設定があるか確認 DNS 設定（/etc/resolv.conf）が正しいか確認 （以下、トラブルシューティングフロー、よくある原因、確認手順、NG行動、FAQ、関連記事、解決しない場合 のセクションが続きます） 許可をお願いします。

症状 docker push 実行時に layer already exists と表示されるが、プッシュが完了しない、またはエラーで失敗する。 結論：まずこれを確認 docker login で認証が正しく行われているか確認する プッシュ先のタグが既存イメージと競合していないか確認する ローカルイメージのタグとリモートリポジトリ名が一致しているか確認する トラブルシューティングフロー flowchart TD A[docker push 失敗] --> B{認証エラー?} B -->|Yes| C[docker login を実行] B -->|No| D{タグ名は正しい?} D -->|No| E[docker tag で正しい名前を付与] D -->|Yes| F{denied エラー?} F -->|Yes| G[リポジトリの権限を確認] F -->|No| H{retrying エラー?} H -->|Yes| I[ネットワーク・レジストリ状態確認] H -->|No| J[キャッシュクリアを検討] C --> K[再度 push を実行] E --> K G --> K I --> K J --> K よくある原因 認証の期限切れ - docker login のセッションが切れている タグ名の不一致 - ローカルイメージのタグがリモートリポジトリ名と一致していない 権限不足 - リポジトリへの push 権限がない レジストリ側の不整合 - リモートに同名レイヤーが破損状態で存在する ネットワークタイムアウト - 大きなレイヤーのアップロード中に接続が切れる ディスク容量不足 - レジストリ側のストレージが不足している プロキシ設定の問題 - 企業ネットワーク等でプロキシが必要 確認手順 ステップ1: 認証状態を確認する docker login <レジストリURL> 🔍 チェックポイント: Login Succeeded が表示されれば認証は正常 ...

症状 Docker コンテナ内でボリュームマウントしたディレクトリにアクセスすると permission denied エラーが発生する。 結論：まずこれを確認 ホスト側のディレクトリ/ファイルの所有者・パーミッションを確認する コンテナ内で実行しているユーザーの UID/GID を確認する SELinux/AppArmor が有効な環境では :z または :Z オプションを試す トラブルシューティングフロー flowchart TD A[permission denied 発生] --> B{ホスト側の<br>パーミッションは?} B -->|読み取り不可| C[chmod/chown で修正] B -->|問題なし| D{コンテナの<br>実行ユーザーは?} D -->|root| E{SELinux/AppArmor<br>有効?} D -->|非root| F[UID/GID 不一致を確認] E -->|Yes| G[:z オプションを追加] E -->|No| H[Docker Desktop の<br>ファイル共有設定を確認] F --> I[--user オプションで<br>UID を指定] C --> J[再度アクセス確認] G --> J H --> J I --> J よくある原因 ホスト側のパーミッション不足 - マウント元のディレクトリ/ファイルに適切な権限がない UID/GID の不一致 - コンテナ内ユーザーとホスト側ファイルの所有者が異なる SELinux のラベル問題 - SELinux 有効環境でコンテキストラベルが付与されていない AppArmor の制限 - AppArmor プロファイルがアクセスを拒否している Docker Desktop のファイル共有設定 - 共有対象ディレクトリに含まれていない（Mac/Windows） 読み取り専用マウント - :ro オプションで書き込みが制限されている 名前付きボリュームの初期化問題 - ボリューム作成時の所有者が異なる 確認手順 ステップ1: エラーメッセージを確認する # コンテナのログを確認 docker logs <container_name> # コンテナ内でコマンド実行時のエラーを確認 docker exec -it <container_name> ls -la /path/to/mount 🔍 チェックポイント: Permission denied の対象がファイルかディレクトリか、読み取りか書き込みかを特定する ...

症状 Docker コンテナ内からホストマシン上のサービス（localhost:3000 など）に接続できない。 結論：まずこれを確認 host.docker.internal を使っているか確認する ホスト側のサービスが 127.0.0.1 ではなく 0.0.0.0 でリッスンしているか確認する ホスト側のファイアウォールがブロックしていないか確認する トラブルシューティングフロー flowchart TD A[コンテナからホストに接続できない] --> B{どのアドレスを使用?} B -->|localhost/127.0.0.1| C[host.docker.internalに変更] B -->|host.docker.internal| D{名前解決できる?} D -->|No| E[Docker Desktop確認/extra_hosts設定] D -->|Yes| F{ホストのサービス起動中?} F -->|No| G[サービスを起動] F -->|Yes| H{0.0.0.0でリッスン?} H -->|No| I[バインドアドレスを変更] H -->|Yes| J{ファイアウォール?} J -->|ブロック| K[ルールを追加] J -->|許可済み| L[ネットワークモード確認] よくある原因 localhost/127.0.0.1 を直接指定している - コンテナ内の localhost はコンテナ自身を指す host.docker.internal が解決できない - Linux では追加設定が必要な場合がある ホストのサービスが 127.0.0.1 のみでリッスン - 外部からの接続を受け付けない設定 ファイアウォールがブロック - iptables/ufw/firewalld がコンテナからの接続を遮断 Docker ネットワークモードの問題 - bridge モードでのルーティング設定不備 ホスト側のサービスが停止中 - そもそも接続先が起動していない ポート番号の間違い - コンテナ側で指定したポートが実際と異なる 確認手順 ステップ1: 接続先アドレスを確認する コンテナ内から接続しようとしているアドレスを確認する。 ...

症状 docker-compose up 実行時に network "ネットワーク名" declared as external, but could not be found または network not found エラーが表示される。 結論：まずこれを確認 docker network ls で対象ネットワークが存在するか確認する 存在しない場合は docker network create ネットワーク名 で作成する 名前が一致しているか docker-compose.yml の networks セクションを確認する トラブルシューティングフロー flowchart TD A[network not found エラー発生] --> B{docker network ls で<br>ネットワークが存在する?} B -->|存在しない| C{external: true<br>が設定されている?} B -->|存在する| D{名前が完全一致<br>している?} C -->|Yes| E[手動でネットワークを作成] C -->|No| F[docker-compose down -v 後<br>再度 up を実行] D -->|Yes| G[Docker Desktop/デーモン<br>を再起動] D -->|No| H[docker-compose.yml の<br>ネットワーク名を修正] E --> I[解決] F --> I G --> I H --> I よくある原因 外部ネットワークが未作成 - external: true を指定したが、ネットワークを事前に作成していない ネットワーク名の不一致 - docker-compose.yml と実際のネットワーク名が異なる（プロジェクト名のプレフィックスを含む/含まない） 以前のネットワークが削除されている - docker-compose down -v や docker system prune でネットワークが削除された プロジェクト名の変更 - ディレクトリ名変更や -p オプションでプロジェクト名が変わった Docker デーモンの再起動 - デーモン再起動後にネットワーク情報がリセットされた（一部環境） typo（タイプミス） - ネットワーク名のスペルミス 確認手順 ステップ1: 現在のネットワーク一覧を確認する docker network ls 🔍 チェックポイント: エラーメッセージに表示されたネットワーク名が一覧に存在するか確認する ...

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」エラーが発生する。 結論：まずこれを確認 COPY 元のステージ名（または番号）が正しいか確認する COPY 元のパスが、前のステージでの実際の出力先と一致しているか確認する 前のステージのビルドが成功しているか確認する トラブルシューティングフロー 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> と一致しているか ...

title: “Dockerコンテナからlocalhostに接続できない” date: 2026-01-16 draft: true description: “Dockerコンテナ内からlocalhostやホストマシンのサービスに接続できない場合の確認手順と対処法を解説” categories: [“runbook”] tags: [“runbook”, “docker”, “localhost”, “ネットワーク”, “接続エラー”, “host.docker.internal”] 症状 Dockerコンテナ内から localhost や 127.0.0.1 に接続しようとすると、接続が拒否される・タイムアウトする 結論：まずこれを確認 コンテナ内の localhost はコンテナ自身を指す（ホストマシンではない） ホストマシンに接続するには host.docker.internal を使用する Linux環境では --add-host オプションが必要な場合がある トラブルシューティングフロー flowchart TD A[コンテナからlocalhostに接続できない] --> B{接続先はどこ?} B -->|ホストマシン上のサービス| C[host.docker.internal を使用] B -->|別のコンテナ| D[同一ネットワークに参加] B -->|コンテナ自身| E[localhost/127.0.0.1 で正しい] C --> F{OSは?} F -->|macOS/Windows| G[そのまま使用可能] F -->|Linux| H[--add-host オプションを追加] D --> I[docker network で確認] E --> J[サービスが起動しているか確認] よくある原因 localhostの誤解 - コンテナ内のlocalhostはコンテナ自身を指す ネットワークモードの問題 - bridgeモードではホストと分離される host.docker.internalの未設定 - Linux環境では自動設定されない ファイアウォールのブロック - ホスト側でDockerからの接続を拒否している サービス未起動 - 接続先のサービスがそもそも起動していない ポートのバインドアドレス - サービスが127.0.0.1のみでリッスンしている Docker Composeのネットワーク設定 - サービス間通信の設定ミス 確認手順 ステップ1: 接続先を明確にする まず、何に接続しようとしているか確認する。 ...

title: “Docker entrypoint.sh で Permission denied エラーが出る” date: 2026-01-14 draft: true categories: [“runbook”] tags: [“runbook”, “docker”, “entrypoint”, “permission-denied”, “シェルスクリプト”, “実行権限”] description: “Dockerコンテナ起動時に entrypoint.sh: Permission denied が表示される場合の確認手順と対処方法” 症状 Dockerコンテナ起動時に以下のようなエラーが表示され、コンテナが即座に終了する。 docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: "/entrypoint.sh": permission denied: unknown または /bin/sh: /entrypoint.sh: Permission denied 結論：まずこれを確認 entrypoint.sh に実行権限があるか確認する 改行コードが LF になっているか確認する shebang（#!/bin/bash）が正しいか確認する トラブルシューティングフロー flowchart TD A[Permission denied エラー] --> B{ホスト側で実行権限を確認} B -->|権限なし| C[chmod +x を実行] B -->|権限あり| D{改行コードを確認} D -->|CRLF| E[LFに変換する] D -->|LF| F{shebangを確認} F -->|問題あり| G[shebangを修正] F -->|正常| H{Dockerfileを確認} H -->|COPY前に権限設定| I[COPYの順序を修正] H -->|問題なし| J[コンテナ内で確認] C --> K[イメージを再ビルド] E --> K G --> K I --> K J --> L[コンテナ内のファイル状態を確認] よくある原因 実行権限がない - ホスト側で chmod +x されていない 改行コードが CRLF - Windows環境で作成したファイルに多い shebang の誤り - #!/bin/bash の記述ミスや不要な空白 Dockerfile の COPY 順序 - 権限設定より先に COPY している Docker キャッシュ - 古いイメージレイヤーが使われている ファイルパスの誤り - Dockerfile 内のパス指定が間違っている ユーザー権限の問題 - コンテナ内で非root実行時に権限が不足 確認手順 ステップ1: ホスト側で実行権限を確認する ls -la entrypoint.sh 🔍 チェックポイント: 出力の左側に x（実行権限）が含まれているか確認 ...

title: “docker exec で Permission denied が出るときの確認手順” date: 2026-01-17 draft: true categories: [“runbook”] tags: [“runbook”, “docker”, “permission denied”, “docker exec”, “コンテナ”, “権限エラー”] description: “docker exec 実行時に Permission denied エラーが出る場合の原因特定と対処手順。ユーザー権限、SELinux、AppArmor、ファイルパーミッションを順に確認する。” 症状 docker exec でコンテナ内のコマンドを実行しようとすると Permission denied エラーが表示される。 OCI runtime exec failed: exec failed: unable to start container process: exec: "xxx": permission denied または bash: /path/to/file: Permission denied 結論：まずこれを確認 実行しようとしているファイルに実行権限があるか確認する コンテナ内のユーザーがそのファイルにアクセスできるか確認する SELinux / AppArmor が有効な環境では、セキュリティコンテキストを確認する トラブルシューティングフロー flowchart TD A[docker exec で Permission denied] --> B{どのタイミングでエラー?} B -->|exec 自体が失敗| C{実行ファイルに +x 権限あり?} B -->|exec 後のコマンドで失敗| D{対象ファイルの権限は?} C -->|No| E[chmod +x で権限付与] C -->|Yes| F{SELinux/AppArmor 有効?} D -->|権限なし| G[chown/chmod で修正] D -->|権限あり| H{コンテナ内ユーザーは?} F -->|Yes| I[セキュリティコンテキスト確認] F -->|No| J[Docker デーモンの権限確認] H -->|root 以外| K[--user オプション確認] H -->|root| L[ボリュームマウントの権限確認] よくある原因 実行ファイルに実行権限がない — シェルスクリプトや実行ファイルに +x がついていない コンテナ内ユーザーとファイル所有者の不一致 — non-root ユーザーで実行している場合に発生しやすい ボリュームマウント時の権限問題 — ホスト側のファイル権限がコンテナ内ユーザーに適用される SELinux が enforcing モード — :z や :Z オプションなしでマウントしている AppArmor プロファイルによる制限 — Ubuntu 系で特定の操作がブロックされる read-only でマウントされている — :ro オプションや read_only 設定が有効 シバン行の問題 — スクリプト先頭の #!/bin/bash が正しくない、または改行コードが CRLF 確認手順 ステップ1: エラーメッセージを正確に確認する docker exec コンテナ名 コマンド 2>&1 🔍 チェックポイント: エラーが exec failed なのか、コマンド実行後の Permission denied なのかを区別する ...

title: “Docker「ポートは既に使用中」エラーの対処法” date: 2026-01-14 draft: true categories: [“runbook”] tags: [“runbook”, “docker”, “port”, “bind”, “address already in use”, “コンテナ”, “ネットワーク”] description: “Dockerでport is already allocated、address already in useエラーが出たときの確認手順と対処法。原因の特定からポート解放まで。” 症状 Dockerコンテナ起動時に「port is already allocated」「Bind for 0.0.0.0:xxxx failed: port is already in use」と表示される。 結論：まずこれを確認 docker ps -a で同じポートを使うコンテナが残っていないか確認 lsof -i :ポート番号 でポートを使用しているプロセスを特定 不要なら停止、必要なら別ポートを使用 トラブルシューティングフロー flowchart TD A[ポート使用中エラー] --> B{docker ps -a で<br>該当コンテナあり?} B -->|Yes| C[docker rm で削除] B -->|No| D{lsof -i :ポート で<br>プロセス特定} D -->|Docker関連| E[docker stop/rm] D -->|他のプロセス| F{そのプロセスは<br>必要?} F -->|Yes| G[別ポートで起動] F -->|No| H[プロセスを停止] C --> I[再度コンテナ起動] E --> I G --> I H --> I よくある原因 停止済みコンテナが残っている - docker stop しても docker rm していないとポート予約が残る場合がある 別のDockerコンテナが同じポートを使用中 - 複数プロジェクトで同じポートを指定している ホストのサービスがポートを使用中 - nginx、Apache、MySQLなどがホストで直接起動している docker-composeの古いコンテナが残存 - プロジェクト名変更後に旧コンテナが残っている 前回のコンテナが正常終了していない - クラッシュや強制終了でゴミが残っている WSL2/Dockerの同期ずれ - Windows環境でDockerとWSL2の状態が不整合 確認手順 ステップ1: エラーメッセージからポート番号を確認する エラーメッセージに含まれるポート番号をメモする。 ...