Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

The Postgres container cannot initialise because its data directory already has files

Errorinitdb: error: directory "/var/lib/postgresql/data" exists but is not empty

Short 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.

  • Applies to postgres Docker image 16, 17 and 18, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/data
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3You changed the tag to 18 or later and kept the old mount path.Postgres 18 moved the volume pathFix

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 pgdata

2Fix

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 5

Confirmed by postgresql.org

Did this fix it?

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 ./pgdata

2Fix

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/data

3Verify

The container starts and creates its own files.

docker compose up -d && docker compose logs db | tail -n 5

Confirmed by hub.docker.com

Did this fix it?

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/postgresql

3Verify

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

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.