docker compose でサービス名が名前解決されず接続できない
docker compose でサービス名が名前解決されないときは、同じネットワークへの所属と依存先の起動完了待ちを揃えれば直る。
別 compose ファイル同士や network_mode: host で起きやすい。
公開: 更新:
docker compose exec worker getent hosts user-db
docker compose exec worker getent hosts user-db 172.23.0.2 user-db user-db
2026-09-23 に local host (Windows 11 Home, Docker 29.1.3)(Node.js 22.14.0 / npm 10.9.2) で実際に打って取った出力。検証環境の詳細
要約
docker compose 内のサービスは、同じ bridge ネットワークに参加していれば、サービス名がそのまま DNS 名 として解決される。db などに繋がらない場合は、まず同じ network にいるかと、依存先がもう起動済みかを確認する。
host ネットワークを使っているときは、そもそも compose の DNS が効かない。
実行例
Windows 11 上の Docker 29.1.3 で試すと、別の compose ファイルから起動した worker では user-db が引けなかった。
getent は何も返さず、終了コード 2 で終わった。
external ネットワーク shared-demo に両方を参加させると、解決できるようになった。
アンダースコア入りの my_db も compose の DNS ではそのまま解決し、aliases で付けた mydb も同じアドレスを返した。
$ docker compose ps --format "table {{.Service}}\t{{.State}}"
SERVICE STATE
api running
user-db running$ docker compose exec api getent hosts user-db
172.21.0.3 user-db user-db
$ echo $?
0$ docker network inspect <project>_default --format "{{range .Containers}}{{.Name}} {{end}}"
dnsdemo3720a-api-1 dnsdemo3720a-user-db-1$ docker compose exec worker getent hosts user-db
$ echo $?
2$ docker network create shared-demo
40c5b82cdb2139a84810e72db205de942efd04d7af780899c7dc53896fdfc192$ docker compose exec worker getent hosts user-db
172.23.0.2 user-db user-db
$ echo $?
0$ docker compose exec api getent hosts my_db
172.21.0.3 my_db my_db
$ echo $?
0$ docker compose exec api getent hosts mydb
172.21.0.3 mydb mydb
$ echo $?
0— 2026-09-23 時点の出力
検証環境Node.js 22.14.0 / npm 10.9.2 / Git 2.48.1.windows.1 / 2026-09-23 検証(ほか 1 件)
- 検証日
- 実行環境
local host (Windows 11 Home, Docker 29.1.3)- バージョン
- Node.js 22.14.0
- npm 10.9.2
- Git 2.48.1.windows.1
- Docker 29.1.3
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. 同一ネットワークか確認
docker compose ps
docker network inspect <project>_defaultContainers 配下に両方のサービスが居れば、同じネットワークに参加できている。
別ファイル間で繋ぐ場合は、片方を external ネットワークに参加させる:
networks:
shared:
external: true
services:
api:
networks: [shared]公式のネットワーキングガイド(新しいタブで開く) に external network の使い方が記載されている。
2. depends_on で起動完了まで待つ
services:
db:
image: postgres
healthcheck:
test: ["CMD", "pg_isready", "-U", "postgres"]
interval: 2s
retries: 10
api:
depends_on:
db:
condition: service_healthycondition: service_healthy を指定すると、healthcheck が成功するまで api が起動しない。
3. host ネットワークを避ける
network_mode: host を使うと bridge の DNS が無効になる。
原則は bridge を使い、compose の旨味(サービス名解決)を保つ。
どうしても必要な場合だけ、IP アドレスや host.docker.internal を使う。
4. サービス名は小文字ハイフン
services:
user-db:
image: postgresアンダースコアを避け、ハイフン区切りか単一単語で命名する。
これは名前解決を直すためというより、文法に厳しいクライアントに当たったときの逃げ道を無くさないための予防である。
既存名を変えにくいなら、aliases で別名を付けてクライアントから使う:
services:
my_db:
networks:
default:
aliases: [mydb]よくある原因
✓ 同じ compose.yaml
✕ 別の compose.yaml で起動
✓ external の共有ネットワーク
- 別のネットワークに居る。
別のcompose.yamlで起動したコンテナ同士は、明示しない限り別ネットワークになり、名前解決できない。 - 起動順だけを見て油断している。
depends_onは起動順を保証するが、プロセスが listen を始めるまでは待ってくれない。 - host ネットワークを使っている。
network_mode: host配下のコンテナは bridge の DNS テーブルに載らず、サービス名を解決できない。 - サービス名にアンダースコアを使っている。
my_dbは DNS のラベル仕様(RFC 1035)やホスト名の文法(RFC 952 / 1123)では許されない文字を含む。
ただし compose の DNS はこの名前も解決する。
詰まるとすればホスト名を厳しく検査するクライアント側で、名前解決そのものが落ちているわけではない。