Updated November 2026. Docker Compose ENOTFOUND db: Service DNS Troubleshooting explains a common deployment failure through reproducible checks, safe fixes and an operator-friendly verification sequence. Run commands only on infrastructure you administer.
Symptoms and likely impact
An app container cannot resolve the configured database host. Record when it began and which users or hosts are affected. An error in the browser may reflect several independent causes in DNS, transport, proxy, application or storage. Start with a single example request and capture its timestamp and response. A precise symptom makes the difference between an efficient diagnosis and repeatedly changing settings that had nothing to do with the original failure.
Preflight and risk assessment
Record software version, deployment type, effective service identity and recent changes. Keep an approved management session open if updating SSH, firewall or remote access rules. Identify available backups and the last known-good release. On shared hosts, avoid stopping unrelated applications or running broad cleanups. Use read-only diagnostics first and confirm the owner of every resource. For changes that touch a database or certificate, plan both verification and restoration.
Diagnostic commands
docker compose ps
docker compose config --services
docker network ls
docker compose exec web getent hosts dbReplace sample hostnames, usernames and service identifiers before running any command. Some checks need administrative access; use only approved privileges. Look for the earliest specific error and correlate it with the actual service or listener. A process that is running does not guarantee a healthy application. If logs contain secrets or private customer information, redact them before sharing in a ticket or asking an assistant for help.
Interpretation: what the error really means
Services across different Compose projects do not automatically share DNS; use explicit supported network configuration. Separate authentication failures from network failures and application crashes. Check the expected destination, listening interface, DNS answer, certificate name and identity when relevant. A successful local check may not reflect the public route through a reverse proxy or content delivery network. Record which layer has been independently confirmed to work and which remains untested before selecting a repair.
Repair the specific cause
Use a shared Compose network and service hostname, not a dynamic IP or host-only published port. Change one relevant setting at a time, preferably in staging or on a single instance. Avoid disabling authentication, TLS validation or the entire firewall as an operational shortcut. Restart only the affected service when needed; preserve logs beforehand. If a deployment created the issue, compare its configuration and dependency versions with the last known-good release. Use official documentation for supported parameters and current vendor requirements.
Validation after the change
The web container resolves db by service name after recreation and connects privately. Repeat the original failing request and a control request known to be valid. Verify both the response and the underlying resource or account state. Check service health after restart and ensure unrelated applications remain available. If the issue involves certificates, examine hostname, chain and expiration. If it involves authentication, verify an unauthorized identity still cannot access the service. Record tested commands, release versions and the final outcome in the incident ticket.
Recovery and rollback
Keep a reversible configuration change and a tested recovery path. A service rollback is different from restoring data, security grants or completed transactions. When the original failure involved login or network access, preserve a working alternate management path until the repair is proven. Never reset a production database or remove arbitrary files simply to silence an error. Escalate if the correct fix requires organizational changes to DNS, vendor permissions or firewall ownership.
Prevent the same outage
Automate the safe check that would have caught the problem before deployment. Add meaningful monitoring for listener availability, failed authentication, certificate expiration, disk pressure or application restart loops. Review alerts against real user impact and avoid collecting unnecessary secrets in standard logging. Check configuration after service restarts because startup ordering may reveal issues hidden during interactive testing. An accurate, reusable runbook reduces future incident response time.
Frequently asked questions
Will restarting the server solve it? Maybe temporarily, but without knowing the cause it can recur and erase useful logs. Should I increase every timeout? No; identify the failing layer. When is the incident closed? Once the original workflow succeeds after validation, unauthorized access remains blocked and recovery steps are documented.
Upstream references
Review the official reference documentation for up-to-date options and supported releases. See also our Linux hardening guide and Nginx reverse proxy tutorial.
