What causes "Umami Docker "Unable to Connect to the Database""?

Hostname in DATABASE_URL doesn't match the database service name in docker-compose.yml Umami starts before PostgreSQL accepts connections Containers on different Docker networks Wrong password or database name APP_SECRET not set (Compose won't start without it since v3.5.0)

How do I fix "Umami Docker "Unable to Connect to the Database""?

1. Read the exact error: Run docker compose logs umami Distinguish a connection refusal or timeout from a 'Cannot find module' crash or a missing-variable error 2. Fix DATABASE_URL: Use the format postgresql://user:password@db:5432/umami where db is the Compose service name Don't use localhost inside the container; it points at the Umami container itself URL-encode special characters in the password 3. Wait for PostgreSQL to be healthy: Add a healthcheck to the db service (pg_isready) Add depends_on: db: condition: service_healthy to the umami service Run docker compose up -d again 4. Set the required variables: Generate a secret with openssl rand -hex 32 Add APP_SECRET= to the .env file next to docker-compose.yml Check that both containers are on the same Docker network

Umami Docker "Unable to Connect to the Database"

Workaround available Self-hosted (Docker, Docker Compose) Updated November 13, 2026Based on 3 user reportsHow we research

Quick answer

The check-db step can't reach PostgreSQL. Usually DATABASE_URL points at the wrong host (it must be the Compose service name, not localhost), Postgres isn't ready yet, or a required variable like APP_SECRET is missing.

Most likely fix: Read the exact error

How to fix it

Try these in order — the most common fix is first.

1. Read the exact error
1. Run docker compose logs umami
2. Distinguish a connection refusal or timeout from a 'Cannot find module' crash or a missing-variable error
Did this fix it?
2. Fix DATABASE_URL
1. Use the format postgresql://user:password@db:5432/umami where db is the Compose service name
2. Don't use localhost inside the container; it points at the Umami container itself
3. URL-encode special characters in the password
Did this fix it?
3. Wait for PostgreSQL to be healthy
1. Add a healthcheck to the db service (pg_isready)
2. Add depends_on: db: condition: service_healthy to the umami service
3. Run docker compose up -d again
Did this fix it?
4. Set the required variables
1. Generate a secret with openssl rand -hex 32
2. Add APP_SECRET=<value> to the .env file next to docker-compose.yml
3. Check that both containers are on the same Docker network
Did this fix it?

Symptoms

docker logs shows 'DATABASE_URL is defined' followed by 'Unable to connect to the database' and the container exits or restarts in a loop.

Why it happens

Hostname in DATABASE_URL doesn't match the database service name in docker-compose.yml
Umami starts before PostgreSQL accepts connections
Containers on different Docker networks
Wrong password or database name
APP_SECRET not set (Compose won't start without it since v3.5.0)

This guide also covers

umami unable to connect to the database
umami docker database error
umami check-db
umami docker compose not starting

Still not working?

If Umami keeps failing, you're not alone. See every Umami problem users report or the alternatives people switch to.

Done fighting Umami? Our small team builds your own Umami alternative, made for how you work. On your domain or hosted by us. Price agreed together.

Get a quote

Fixed it? Share this guide

The same problem in other apps

All not loading, error messages & connection guides →

PostHog Toolbar or Heatmaps Not Loading (PostHog)

Other Umami errors

All 12 Umami errors and fixes →