FATAL: password authentication failed for user "weblate" when starting Weblate dev stack

Short answer

Yes: define a healthcheck on the db service and gate the Weblate service on it with depends_on: / condition: service_healthy. With Docker Compose v2 (the Compose specification), that is the recommended approach and a wait-for-it.sh wrapper is redundant. But be aware of a second, more common cause: password authentication failed is usually a credentials mismatch, not a timing problem, and no healthcheck fixes that.

The healthcheck and dependency

PostgreSQL ships pg_isready, which is exactly what a readiness healthcheck should use:

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: weblate
      POSTGRES_PASSWORD: weblate
      POSTGRES_DB: weblate
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U weblate -d weblate"]
      interval: 5s
      timeout: 3s
      retries: 12

  weblate:
    depends_on:
      db:
        condition: service_healthy

pg_isready exits 0 once the server accepts connections, and Compose will not start weblate until the check passes. This works across branches and image tags because it polls actual readiness instead of guessing with sleep 10.

When the healthcheck is not enough

If the error persists after the db container reports healthy, the cause is almost certainly stale credentials. PostgreSQL initializes the role and password from POSTGRES_USER/POSTGRES_PASSWORD only on first boot of an empty data directory. If the named volume was created earlier with different values (a branch switch, an edited compose file), the old password stays and every connection fails with exactly this FATAL message. The fix is to re-initialize:

docker compose -f docker-compose-dev.yml down -v
docker compose -f docker-compose-dev.yml up

down -v deletes the postgres volume, which is acceptable in a dev stack but destroys any local data. Alternatively, keep the volume and align the password manually with ALTER ROLE weblate WITH PASSWORD '...'; via docker compose exec db psql -U postgres.

Version caveats

condition: service_healthy is honored by Docker Compose v2 (docker compose). Legacy docker-compose 1.x with a v3 file, and swarm mode, ignore or reject the condition — check with docker compose version. Only on those legacy setups would a polling wait script (looping on pg_isready, never a fixed sleep) be the fallback. Also note pg_isready proves the server is up, not that the weblate role/database match Weblate's WEBLATE_DATABASE_* settings, so keep those variables identical to the db service's environment.

Verifying which problem you have

1. docker compose logs db — if PostgreSQL logs the auth failure repeatedly while healthy, it is credentials, not ordering.
2. docker compose exec db pg_isready -U weblate -d weblate — confirms the healthcheck target.
3. From the weblate container, try psql -h db -U weblate with the configured password to reproduce the failure directly.

If you can share whether the volume predates the current compose file (or whether docker compose version reports v2), that would confirm which of the two fixes applies — but the healthcheck plus service_healthy is correct in either case.