---
title: "Discussion on \"docker compose depends_on does not wait for your database: fix \"connection refused\" on startup with healthchecks\" | Hashnode"
description: "Discussion on \"docker compose depends_on does not wait for your database: fix \"connection refused\" on startup with healthchecks\". Your app crashes with ECONNREFUSED or \"could not connect to server\" on docker compose up, then works on the second try. Why depends_on only waits for the container to start, the healthcheck fix, the service_healthy trap, and a free VS Code extension that flags it."
url: "https://hashnode.com/posts/readywait-docker-compose-depends-on-connection-refused/6ad58c3e9d03041a783b3468"
---

[Feed](https://hashnode.com/feed) /

Discussion

# [docker compose depends\_on does not wait for your database: fix "connection refused" on startup with healthchecks](https://jaytank.hashnode.dev/readywait-docker-compose-depends-on-connection-refused?utm_source=hashnode&utm_medium=feed)

Your app crashes with ECONNREFUSED or "could not connect to server" on docker compose up, then works on the second try. Why depends\_on only waits for the container to start, the healthcheck fix, the service\_healthy trap, and a free VS Code extension that flags it.

Oct 19 · 10 min read · jaytank.hashnode.dev  
Read the article

-   [#docker](https://hashnode.com/tag/docker)
-   [#docker-compose](https://hashnode.com/tag/docker-compose)
-   [#devops](https://hashnode.com/tag/devops)
-   [#vs-code](https://hashnode.com/tag/vs-code)
-   [#postgresql](https://hashnode.com/tag/postgresql)

## Written by

[JAY TANK](https://hashnode.com/@jaytank)

@jaytank

  
[View profile](https://hashnode.com/@jaytank)

Engineering insights on building and scaling modern software.

Cloud &amp; Platform Engineer focused on building systems that scale and endure. I explore how infrastructure, automation, and engineering practices come together to support modern software teams.

## Responses 1

Markdown supported · ⌘↵ to post

[Node Edge Ops](https://hashnode.com/@nodeedgeops)

[Nov 5](https://hashnode.com/posts/readywait-docker-compose-depends-on-connection-refused/6ad58c3e9d03041a783b3468/comment/6aec32707d584025595dccc5)

depends\_on alone only waits for the container process to exist, not for Postgres (or any DB) to accept queries — so a Node API that connects in its top-level boot still dies with ECONNREFUSED while the DB is still initializing. Gate the API with a real healthcheck on the DB service and depends\_on condition service\_healthy, keep the probe cheap (pg\_isready / equivalent, not a heavy query), and still add a short connect retry with backoff in the Node boot path: TCP-ready is not the same as accepting auth, recovering WAL, or finishing a restore.

Ops check after the compose change: bring the stack up from a cold state, confirm the API container stays Running without a crash-loop before the DB flips healthy, then hit a readiness route that opens a pooled connection once. If the API still flaps, the healthcheck is too optimistic (interval/retries too tight) or the app still connects at import time before your retry wrapper runs — move the first pool connect behind an async bootstrap, not a require-time side effect.
