The Postgres container cannot initialise because its data directory already has files
initdb: error: directory "/var/lib/postgresql/data" exists but is not emptyShort answer
initdb refuses to run in a directory that already has anything in it. In Docker that means the path you mounted contains files: a volume root with lost+found, a host folder with leftovers, or, since Postgres 18, a mount at the old path. Point PGDATA at a clean subdirectory or fix the mount path.
Fix it fast
1Find out which cause you have
List what is in the directory the container sees. The names tell you which cause applies.
docker run --rm -v "$PWD/pgdata:/var/lib/postgresql/data" postgres:17 ls -la /var/lib/postgresql/data2Match what you see, then jump to its fix
- 1
The output lists lost+found, and the directory is a dedicated disk or volume.The mount point itself is the data directory and holds lost+foundFix - 2
The listing shows files that are not a Postgres cluster (no PG_VERSION file).A host folder with unrelated or half-copied files is mountedFix - 3
You changed the tag to 18 or later and kept the old mount path.Postgres 18 moved the volume pathFix
- 1
What does the error look like?
initdb: error: directory "/var/lib/postgresql/data" exists but is not empty
Cause 1 of 3
The mount point itself is the data directory and holds lost+found
1Check
A freshly formatted disk or network volume often has lost+found at its root. PostgreSQL's guidance is not to use the topmost directory of a mounted volume as the data directory.
docker volume inspect pgdata2Fix
Keep the mount, but tell Postgres to put the cluster in a subdirectory of it.
services:
db:
image: postgres:17
environment:
PGDATA: /var/lib/postgresql/data/pgdata
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:3Verify
Start again; the log shows the database system is ready to accept connections.
docker compose up -d && docker compose logs db | tail -n 5Confirmed by postgresql.org
Cause 2 of 3
A host folder with unrelated or half-copied files is mounted
1Check
Initialisation, and the password and init scripts that come with it, only run when the data directory is empty.
ls -la ./pgdata2Fix
Mount a new empty folder, or use a named volume. Move anything you still need out first.
mkdir -p ./pgdata-new
# then mount ./pgdata-new:/var/lib/postgresql/data3Verify
The container starts and creates its own files.
docker compose up -d && docker compose logs db | tail -n 5Confirmed by hub.docker.com
Cause 3 of 3
Postgres 18 moved the volume path
1Check
From version 18 the image declares its volume at /var/lib/postgresql and keeps data in a version-specific folder. Older versions use /var/lib/postgresql/data.
docker image inspect postgres:18 --format '{{.Config.Volumes}} {{.Config.Env}}'2Fix
Mount at /var/lib/postgresql for 18 and later. Existing data from an older major version must be moved with pg_upgrade or a dump and restore, not by pointing the new image at it.
volumes:
- pgdata:/var/lib/postgresql3Verify
A new empty volume starts cleanly on 18.
docker compose up -d && docker compose exec db psql -U postgres -c 'show data_directory'Confirmed by hub.docker.com
How do I stop it coming back?
- Set PGDATA to a subdirectory when the mount is a dedicated disk or network share.
- Check the image documentation for the volume path before changing the major version tag.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Databases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
EF Core says 'transient failure' when it cannot reach PostgreSQL in Docker
The query fails only after a delay, because the connection is retried several times
The transient failure message comes from EF Core's retry layer, which hides the underlying connection error.
3 causes, each with a fixDatabases
A Postgres query in Docker fails with: could not resize shared memory segment
ERROR: could not resize shared memory segment: No space left on device
Postgres in a container hands query memory to parallel workers through the container's /dev/shm.
2 causes, each with a fixDatabases
The Postgres container refuses to start: data directory has invalid permissions
mkdir: cannot create directory ‘/home/postgres/pgdata/data’: permission denied
Postgres starts only when its data directory is owned by the server user and closed to everyone else: mode 0700, or 0750 when group read is enabled.
3 causes, each with a fixDatabases
The postgres container exits when ssl=on and a mounted certificate
the container exits a second after docker compose up, and the log names server.crt or server.key
With ssl=on, PostgreSQL refuses to start if it cannot use the certificate and key.
3 causes, each with a fixDatabases
The Postgres container cannot set permissions on a bind-mounted data folder
chmod: changing permissions of '/var/lib/postgresql/data': Operation not permitted
Postgres needs its data directory owned by the server user with mode 0700.
3 causes, each with a fix