動かない時

コンテナが起動しない

「起動しない」ときに最初に確認すべき `docker ps -a` / `docker logs` / `docker inspect` の見方と、exit code 別の典型原因。

症状

docker run すると一瞬で終わる（docker ps には表示されない）
docker compose up すると exited with code 1 / code 137 / code 139 などと出て止まる
restart: always にしているのに繰り返し再起動ループを起こしている
エラーメッセージが画面に出ず、「とにかく起動しない」としか分からない

原因

exit code はカーネル・ランタイム・アプリから返る数値で、原因切り分けの第一ヒントです。

Exit code	よくある意味
`0`	正常終了。サービスコンテナが即 0 で終わるのは、一度きりの処理で設計通りのことも多い
`1`	アプリ内部エラー（未捕捉例外、設定ファイル不正など）
`125`	Docker デーモンのエラー（run 自体に失敗。`-v` パス無効など）
`126`	コマンドは見つかったが実行権限なし
`127`	`command not found`（PATH ミス、タイポ、マルチアーキ不整合）
`137`	`SIGKILL`（128 + 9）。OOM で kill / `docker kill` / Kubernetes が liveness 失敗で強制終了
`139`	`SIGSEGV`（128 + 11）。セグフォ。ネイティブ拡張や QEMU エミュレーション起因が多い
`143`	`SIGTERM`（128 + 15）。`docker stop` などでの正常停止

まずは exit code を docker ps -a で見て当たりをつけます。

確認コマンド

bash

# すべてのコンテナ（終了済み含む）と exit code を確認
docker ps -a

# 直近のコンテナのログ（タイムスタンプ付き、末尾 200 行）
docker logs --timestamps --tail 200 <container>

# 起動試行中にリアルタイムで見る
docker logs -f <container>

# 状態の詳細（exit code、OOMKilled、ExitCode、Error メッセージ）
docker inspect <container> --format '{{json .State}}' | jq

# 再起動ループの場合、RestartCount と LastState
docker inspect <container> --format '{{.RestartCount}} {{json .State}}' | jq

# イメージの ENTRYPOINT / CMD が妥当か
docker image inspect <image> --format 'Entrypoint: {{.Config.Entrypoint}}\nCmd: {{.Config.Cmd}}\nUser: {{.Config.User}}\nWorkingDir: {{.Config.WorkingDir}}'

# コマンドを上書きしてシェルに入って直接実行（デバッグの鉄板）
docker run --rm -it --entrypoint sh <image>
# 入れたらアプリ起動コマンドを手動で叩いて本当のエラーを見る

解決策

exit code 別のアプローチ:
- 1: docker logs にアプリのスタックトレースが出ているはず。設定ファイルパス、環境変数、DB 接続先などを再確認
- 125: docker run のオプションを疑う。-v /存在しないパス:/app や --network=存在しないネット など、Docker 本体が拒否している。コマンドをそのまま読み返すとたいてい気付く
- 126 / 127: Dockerfile の ENTRYPOINT / CMD、スクリプトファイルの実行権限（chmod +x）、改行コード（Windows の CRLF だとシェルが解釈に失敗）を確認
- 137: メモリ不足。docker stats でメモリ使用量を観察し、-m 512m 等の制限が厳しすぎないか、アプリのリーク、または Docker Desktop に割り当てたメモリ不足を疑う
- 139: アーキ不整合や QEMU の不具合。trouble-arm64-vs-amd64 を参照
デバッグの鉄板手順:
1. docker run --rm -it --entrypoint sh <image> で起動形態を疑似化してシェルを奪う
2. 実際の ENTRYPOINT / CMD を手動で実行し、本当のエラー出力を読む
3. 必要なファイル・環境変数・権限がコンテナ内に揃っているか ls -la, env, id で確認
再起動ループ対策: docker inspect の RestartCount と LastState.Error を見る。restart: always を一時的に no にしてからログを読むと落ち着いて調べられる
Compose の場合: docker compose logs <service> で個別サービスのログを見る。depends_on: で依存している別サービスが先に死んでいないかも確認
ヘルスチェック失敗での restart: HEALTHCHECK を仕込んでいる場合、ヘルスチェック失敗が原因で延々 restart していることがある。docker inspect の .State.Health.Log を確認