Docker Compose

冒頭まとめ docker compose の実行中に現れる 429 Too Many Requests は、ほぼ例外なく Docker Hub の pull 回数制限です。制限そのものの仕組み（匿名は IP 単位、認証済みはアカウント単位）は Compose に固有の話ではありません（Docker の 429 の記事）。 Compose に固有なのは、同じ作業でも要求の回数と同時実行数が増えやすいという点です。増幅の要因は3つあります。 1つ目は並列度です。公式のリファレンスによれば、--parallel の既定値は -1、つまり無制限です。15 サービスの構成なら、15 件の取得要求がほぼ同時に飛びます。 2つ目はタグです。公式文書には、既定の missing という方針であっても latest タグだけは常に取得される、と明記されています。実装を読むと、手元にイメージがあるかを判定する関数が、タグが latest のときは「無い」と扱う作りになっています。image: nginx のようにタグを省略した記述は latest を指すため、up のたびにレジストリへ問い合わせが行きます。 3つ目は取得方針です。pull_policy: always や docker compose up --pull always を使っていると、手元にあっても毎回取得します。 さらに、Compose の取得処理には再試行の仕組みがありません。制限に当たれば、その場で失敗します。 したがって対処の順序は、上限を増やすことではなく、この3つの増幅要因を減らすことから始まります。 エラーの概要 docker compose pull や docker compose up の実行中に、次の形で現れます。 [+] Pulling 3/5 ✔ redis Pulled ✘ web Error toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: ... ✘ api Error toomanyrequests: You have reached your pull rate limit. Error response from daemon: toomanyrequests: You have reached your pull rate limit. 注目すべきは、複数のサービスが同時に失敗する点です。単発の docker pull なら1件で終わるところが、並列に走っているため、残り枠を一気に使い切ってまとめて弾かれます。 ...

エラーの概要 Docker Compose で 403 エラーが発生する場合、これはレジストリ（Docker Hub、プライベートレジストリなど）またはホストマシンのリソースに対して、実行ユーザーが十分なアクセス権限を持っていないことを示しています。プライベートイメージの pull、ボリュームマウント時のファイルアクセス、Docker ソケットへのアクセスなど、複数の場面で発生する可能性があります。 実際のエラーメッセージ例 Docker Hub などのレジストリからのプライベートイメージ pull 時： { "message": "Error response from daemon: pull access denied for myregistry/myimage, repository does not exist or may require 'docker login'", "error": "403 Forbidden" } ボリュームマウントのパーミッション不足時： ERROR: for <service-name> Cannot start service <service-name>: error while creating mount source path '/data/app': permission denied Docker ソケットへのアクセス権限不足時： ERROR: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock よくある原因と解決手順 原因1：プライベートイメージレジストリへの認証不足 Docker Compose でプライベートイメージを利用する場合、レジストリに対する認証情報が必要です。認証なしにプライベートイメージを pull しようとすると 403 エラーが発生します。 ...

エラーの概要 Docker Compose の 404 エラーは、docker-compose.yml（または compose.yml）で指定されたイメージ、サービス、ボリューム、またはネットワークがシステムに見つからないときに発生します。このエラーは、イメージのプル失敗、ビルドコンテキストの誤設定、または依存リソースの不足が原因となることがほとんどです。Docker Compose がコンテナーの起動や構築を試みた際に、参照先が存在しないことを検出すると、このエラーを出力して処理を中断します。 実際のエラーメッセージ例 Error response from daemon: pull access denied for <your-image-name>, repository does not exist or may require 'docker login' または、より明確な 404 表現として： { "message": "manifest not found", "status": 404 } ローカルでのビルド失敗時： ERROR: Service '<your-service-name>' failed to build : [Errno 2] No such file or directory: '<your-build-context-path>' よくある原因と解決手順 原因1：compose.yml 内で指定したイメージが存在しない、またはタグが間違っている Docker Compose がレジストリ（Docker Hub やプライベートレジストリー）からイメージをプルしようとしても、そのイメージが存在しない、あるいはタグが誤っていると 404 エラーが発生します。たとえば、タイポやバージョン番号の誤指定があると、プル対象が見つからなくなります。 Before（エラーが起きるコード）： version: '3.8' services: web: image: nginx:lattest # タイポ: lattest → latest ports: - "80:80" After（修正後）： ...

エラーの概要 Docker Compose の 409 エラーは、リクエストされたコンテナーやネットワーク、ボリュームの状態が現在の環境状態と競合していることを示します。このエラーは通常、既に存在するリソースの作成を試みたり、使用中のポート・ネットワークを重複させたりした場合に発生します。既存の状態を認識しないまま操作を進めようとすると、Docker Compose がこの競合を検出して実行を中止します。 実際のエラーメッセージ例 パターン1：コンテナー名の競合 Error response from daemon: Conflict. The container name "<container-name>" is already in use by container "<existing-container-id>". You have to remove (or rename) that container to be able to reuse that name. パターン2：ポート番号の競合 ERROR: for <service-name> Cannot start service <service-name>: driver failed programming external connectivity on endpoint <endpoint-name>: Bind for 0.0.0.0:<port> failed: port is already allocated パターン3：ネットワークまたはボリュームの競合 Error response from daemon: network with name <network-name> already exists よくある原因と解決手順 原因1：同じ名前のコンテナーがすでに起動または停止状態で残っている Docker Compose は docker-compose.yml で定義したサービス名とプロジェクト名の組み合わせでコンテナー名を生成します。以前に作成したコンテナーが停止状態で残っていたり、同じ構成を再度実行しようとしたりすると、同じ名前のコンテナーが存在することになり、409 エラーが発生します。 修正方法： # 既存のコンテナーと関連リソースを完全に削除 docker compose down -v # その後、新たに起動 docker compose up -d -v フラグでボリュームも削除されるため、データの永続化が必要な場合は事前にバックアップを取得してください。 原因2：同じポートを複数のサービスが使おうとしている docker-compose.yml で複数のサービスが同じホストポートをバインドしようとしている場合、またはホストシステムの別のプロセスがすでにそのポートを使用している場合に 409 エラーが発生します。 修正方法： version: '3.8' services: web1: image: nginx:latest ports: - "8080:80" web2: image: nginx:latest ports: - "8081:80" 各サービスに異なるホストポートを割り当てることで競合を解決します。既にポートが使用されている場合は、以下のコマンドでホストマシン上の使用中ポートを確認できます。 ...

エラーの概要 Docker Compose の 500 エラーは、Docker Compose 自体またはそれが管理するコンテナー内で内部エラーが発生したことを示します。このエラーは通常、コンテナー起動時のアプリケーションクラッシュ、エントリポイント実行の失敗、またはヘルスチェック機構の不具合によって引き起こされます。対象のサービスが正常に起動・稼働できない状態を意味しており、迅速な原因特定と対応が必要です。 実際のエラーメッセージ例 Docker Compose でコンテナーが起動に失敗した際の典型的なエラー出力は以下の通りです。 ERROR: for <service-name> Cannot start service <service-name>: OCI runtime create failed: container_linux.go:380: starting container process caused: exec: "<command>": executable file not found in $PATH: unknown または、ヘルスチェック失敗時は以下のように表示されます。 <service-name> | ERROR: Health check failed. Retrying... <service-name> | (Exit status: 1) アプリケーション実行時のエラーログは以下のようなパターンです。 docker-compose logs <service-name> <service-name> | Traceback (most recent call last): <service-name> | File "/app/main.py", line 15, in <module> <service-name> | raise Exception("Database connection failed") <service-name> | Exception: Database connection failed よくある原因と解決手順 原因1：サービスのコンテナー内部でアプリケーションがクラッシュしている コンテナー起動後、アプリケーションが異常終了またはランタイムエラーで落ちてしまう状況です。これは依存関係の欠落、設定ファイルの不在、メモリ不足、または不正な初期化処理によって発生します。 ...

エラーの概要 503エラーは「Service Unavailable」を意味し、Docker Composeでは依存するサービスが正常に起動できていない、または起動完了前にアクセスされている状況を示します。マイクロサービスアーキテクチャではよく発生するエラーで、特に複数コンテナーの起動順序やヘルスチェック設定に起因することが多いです。 実際のエラーメッセージ例 Docker Composeで503エラーが発生した際のログ例を以下に示します。 { "status": 503, "message": "Service Unavailable", "error": "connect ECONNREFUSED 172.20.0.3:5432" } docker compose logs app-service 2024-01-15T10:23:45.123Z ERROR Failed to connect to database: ECONNREFUSED 2024-01-15T10:23:46.456Z WARN Service startup failed, retrying... 2024-01-15T10:23:50.789Z ERROR Max retries exceeded よくある原因と解決手順 原因1：depends_onで依存関係を定義しているが、ヘルスチェック待機を設定していない マイクロサービス構成では、アプリケーションコンテナーがデータベースコンテナーの完全な起動完了を待つ必要があります。docker compose up実行時、デフォルトでは依存するコンテナーが「起動した」ことだけを確認して先に進むため、データベースが受け入れ準備完了する前にアクセスされます。 Before（エラーが起きるコード）： version: '3.8' services: postgres: image: postgres:15 environment: POSTGRES_PASSWORD: password ports: - "5432:5432" app: image: myapp:latest depends_on: - postgres ports: - "8080:8080" After（修正後）： version: '3.8' services: postgres: image: postgres:15 environment: POSTGRES_PASSWORD: password ports: - "5432:5432" healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s timeout: 5s retries: 5 app: image: myapp:latest depends_on: postgres: condition: service_healthy ports: - "8080:8080" 上記の修正では、service_healthy条件によってPostgresのヘルスチェック成功を待ってからアプリケーション起動が開始されます。 ...

Windows環境でDocker Composeを使う際、PowerShellで作成した.envファイルが原因でコンテナが起動できないケースがあります。エラーメッセージに\xff\xfeやunexpected characterが含まれている場合、ファイルのエンコードが原因です。 エラーの全文 failed to read C:\Users\user\project\.env: line 1: unexpected character "?" in variable name "\xff\xfeG\x00O\x00O\x00G\x00L\x00E\x00_\x00A\x00P\x00I\x00_\x00K\x00E\x00Y\x00=\x00A\x00I\x00z\x00a\x00..." \xff\xfe はUTF-16 LEのBOM（Byte Order Mark）です。続く\x00が各文字の後ろに並んでいることから、ファイル全体がUTF-16 LEで保存されていることがわかります。Docker ComposeのenvファイルパーサーはUTF-8（BOMなし）のみを受け付けるため、このファイルを読み込もうとした瞬間にクラッシュします。 よくある原因 PowerShellのechoコマンドはUTF-16 LEで書き出す WindowsのPowerShell（5.1系）では、リダイレクト演算子>やechoコマンドがデフォルトでUTF-16 LE（BOM付き）を使用します。 # これをやってはいけない echo GOOGLE_API_KEY=AIzaSy... > .env # → .envがUTF-16 LE（BOM付き）で保存される Linuxや macOSのシェルと違い、PowerShellは歴史的な経緯からUTF-16をデフォルトエンコードとして採用しています。echoやSet-Contentを使う限り、意識しない限りこの問題が発生します。 VSCodeのエンコード設定が変わっている場合 VSCodeでファイルを新規作成・保存する際、右下のステータスバーが「UTF-16 LE」になっているとDocker Composeが読めないファイルが生成されます。 診断方法 .envファイルの先頭バイトを確認します。 # 先頭4バイトを16進数で確認 $bytes = [System.IO.File]::ReadAllBytes(".env") $bytes[0..3] | ForEach-Object { $_.ToString("X2") } 正常（UTF-8 BOMなし）: 47 4F 4F 47 ← "GOOG"の文字コード（例：GOOGLE_API_KEY=...） 異常（UTF-16 LE BOM付き）: FF FE 47 00 ← \xff\xfe がBOM、その後\x00が混入 解決手順 方法1：既存の.envファイルをUTF-8に変換する（即時対応） # UTF-16で書かれた.envをUTF-8（BOMなし）に変換して上書き $content = Get-Content ".env" -Encoding Unicode -Raw [System.IO.File]::WriteAllText( (Resolve-Path ".env").Path, $content.Trim() + "`n", [System.Text.UTF8Encoding]::new($false) ) $falseは「BOMを付けない」を意味します。UTF8Encoding::new($true)にするとBOM付きになるため注意してください。 ...

エラーの概要 Docker Composeで400エラーが発生する場合、compose.yml（またはdocker-compose.yml）の設定に問題があるか、コマンドのオプション指定が誤っている可能性があります。このエラーはCompose自体が設定ファイルを正しくパースできないことを示しており、設定ファイルの検証とコマンド構文の確認により、ほぼすべてのケースで解決します。 実際のエラーメッセージ例 ERROR: The Compose file './docker-compose.yml' is invalid because: service 'web' has unsupported config option: 'cointainer_name' { "error": "Invalid service configuration", "message": "service 'db' config has unsupported option: 'envrionment'", "code": 400 } Error response from daemon: Ports must be expressed as "port" (a number) or "port/protocol" (a string). よくある原因と解決手順 原因1：compose.ymlのYAML構文エラー（インデント・タブ混在） YAML形式の構文ミスが最も多い原因です。インデント（スペース）の不一致、タブ文字の混在、コロンの後の空白忘れなどが該当します。YAMLはインデントに非常に敏感であり、2文字か4文字のスペースで統一する必要があります。タブ文字を使用するとパーサーが正しく解釈できず、400エラーが発生します。 Before（エラーが起きるコード）： version: '3.8' services: web: image: nginx:latest ports: # タブ文字が混在している - "80:80" db: image: postgres:13 # インデントが統一されていない（スペース数が異なる） environment: POSTGRES_PASSWORD: secret After（修正後）： version: '3.8' services: web: image: nginx:latest ports: - "80:80" db: image: postgres:13 environment: POSTGRES_PASSWORD: secret 原因2：サービス定義の必須キー不足または値の型エラー serviceセクション内で必須キーが欠けている、または値の型が仕様と異なる場合も400エラーになります。例えば、portsに文字列を指定すべきところに数値を指定したり、environmentをリスト形式で記述すべきところにオブジェクト形式で書いたりすると発生します。また、キー名のタイプミス（cointainer_nameなど）も認識されずエラーとなります。 ...

エラーの概要 Docker Composeで401エラーが発生する場合、コンテナレジストリーへの認証に失敗しています。このエラーはプライベートイメージをpullしようとする際に最も頻繁に発生し、レジストリー側が「認証情報が不正または未提供」と判定した状態です。Docker Hubやプライベートレジストリー（ECR、GCR、プライベートDockerレジストリーなど）の両方で起こりえます。 実際のエラーメッセージ例 ERROR: for <service-name> UnexpectedStatusError(401): 401 Client Error: Unauthorized for url: https://index.docker.io/v2/<image-name>/manifests/latest { "message": "unauthorized: authentication required", "details": "https://docs.docker.com/docker-hub/access-tokens/" } ERROR: for myapp pull access denied for myregistry.azurecr.io/myimage, repository does not exist or may require 'docker login': denied: authentication required よくある原因と解決手順 原因1：docker loginを実行していない Docker Composeでプライベートイメージをpullする前に、docker loginコマンドで認証を済ませていない状況です。認証情報が~/.docker/config.jsonに保存されていないため、レジストリー側は401で応答します。 Before（エラーが起きるコード）： # 認証なしで直接実行 $ docker-compose up ERROR: for webapp UnexpectedStatusError(401): 401 Client Error: Unauthorized After（修正後）： # 1. 先に認証を完了させる $ docker login Username: <your-username> Password: <your-password> Login Succeeded # 2. その後にdocker-composeを実行 $ docker-compose up 原因2：compose.ymlで正しい認証情報が参照されていない compose.ymlにレジストリー認証情報を含めるとき、x-aws-cred-helperやcredHelpers設定が不正な場合や、設定ファイル自体が存在しない場合に401が発生します。 ...