Docker depends_on: Database Not Ready

Starting a database container does not mean the database is ready to accept the application's requests. Compose dependency order and service readiness are different checks. Define a meaningful readiness condition and make the application handle later connection failures too.

Confirm the timing pattern

Compare logs from the application and database using timestamps. Does the first connection fail before the database announces readiness? Does restarting only the app then succeed?

That pattern suggests a startup race, but also inspect credentials and database names. A wrong password will not become correct after a longer sleep.

Docker's startup-order guide describes health-based dependency conditions. Use syntax supported by your Compose version and the command you actually run.

Make the health check useful

A running process is a weak readiness signal. A database readiness check should establish the level of service the dependent application requires, without performing destructive operations.

If schema migrations must complete before the app starts, represent that dependency separately. Database readiness does not guarantee the expected tables exist.

Dependency	Useful evidence
Database process	Accepts appropriate connections
Schema migration	Completed successfully
External API	Required endpoint reachable and authorized
Local model service	Intended model request can complete

Avoid a single long sleep. It may be unnecessarily slow on one machine and still too short on another.

Keep runtime recovery in the application

A startup condition only helps at startup. The database can restart later, connections can expire and networks can fail.

Use bounded retries with backoff for retryable connection failures. Ensure writes do not execute twice when a response is lost. Permanent authentication or schema errors should produce an actionable failure rather than an endless retry loop.

Historical Compose issue reports also show why old command behavior should not be assumed to match current releases. Record your versions and reproduce the exact command.

Test more than a clean boot

Run a normal cold startup in a test environment. Then deliberately delay the dependency and confirm the app waits or fails clearly. Finally, restart the dependency after the app has been running.

Success means the application either reconnects correctly or reports an understandable unavailable state. It should not claim readiness while every user request fails.

Keep a small incident record

Save startup timestamps, health-check outcomes and the first application error. This is more useful than a screenshot showing that all containers are “up.”

For agent applications described in AI agent architecture, the same principle applies to queues, model servers and tool services. Readiness should describe the actual capability the next step needs.

Related troubleshooting

• Docker Cannot Reach an API on Your Laptop
• API Timeout: Is It Safe to Retry?

This guide draws on the linked documentation. Examples are illustrative unless explicitly identified as measured results.