Checked on PostgreSQL 19 RC2 and 18.7 · Updated

"Error: in 18+, these Docker images are configured to store database data…" after pulling PostgreSQL 19 with postgres:latest

Correction, 20 November 2026. PostgreSQL released the server on 19 November. Docker Hub pushed the updated floating tags at 04:11 UTC on 20 November. If you use a floating tag with PostgreSQL 18 data, pin the matching 18 variant before your next pull and recreate. PostgreSQL release announcement · Docker Hub tag metadata

At 04:35 UTC on 20 November, we compared the Docker Hub image digests for each Linux platform.

  • postgres:latest (also used by bare postgres) and postgres:trixie matched postgres:19 and postgres:19-trixie, respectively, on linux/amd64, linux/386, linux/arm/v5, linux/arm/v7, linux/arm64/v8, linux/ppc64le and linux/s390x.
  • postgres:alpine, postgres:alpine3.24 and postgres:alpine3.23 matched their 19 counterparts on linux/amd64, linux/386, linux/arm/v6, linux/arm/v7, linux/arm64/v8, linux/ppc64le and linux/s390x.
  • postgres:bookworm matched postgres:19-bookworm on all five listed platforms (linux/amd64, linux/386, linux/arm/v7, linux/arm64/v8 and linux/ppc64le).
  • On linux/riscv64, latest, trixie and the three Alpine tags still matched their 18 counterparts. Their 19 counterparts had no RISC-V entry at that read.

We ran both PostgreSQL 19 release candidates on 18 data, RC1 on 30 October and RC2 on 13 November. In the default volume layout, each printed the error in the title and exited with code 1. Pinning postgres:18 started the same volume again with every row in place.

A Docker Hub index digest identifies the whole index. Two tags can share a platform image while their index digests differ. A registry mirror can serve a different image for the same tag. Your local tag can still point to a cached 18 image after Docker Hub moves to 19. An existing container keeps the image it started with until it is recreated.

In our tests with the default pull policy, Compose v2.24.6, v2.27.0 and v5.4.0 each started a cached latest image with docker compose up without pulling. Compose's documentation says latest "is always pulled". For an existing 18 volume, the change to watch for is a pull of the 19 image for your platform followed by a container recreate. That can happen with docker compose pull followed by docker compose up -d, with docker compose up --pull always, or when an image auto-updater or deploy job pulls and recreates the container. The Compose reference also lists pull policies that can fetch a newer image, including pull_policy: always and, when the last pull was more than 24 hours ago, pull_policy: daily.

This page has the release-candidate errors for three volume layouts, a one-line check, the pin, and two upgrades we ran on the release candidates (pg_upgrade --link and dump and restore).

Check your stack today

In the folder with your Compose file:

docker compose config --images | grep -E '(^|/)postgres(:(latest|trixie|bookworm|alpine|alpine3\.2[34]))?$'

Each line shows a resolved image reference whose repository name is postgres and whose tag is one of the floating tags above or omitted. Compose substitutes variables first, so image: postgres:${PG_TAG:-latest} matches when PG_TAG is unset or empty. Setting PG_TAG=18 removes that match. The pattern also matches mirrors and unofficial repositories named postgres. Check the registry and namespace before applying the Docker Hub results.

If Compose prints an error, fix it and rerun the check. If your database uses a Compose profile, enable the same profile you use to start it.

To check a running database, connect to it in your usual SQL client and run SHOW server_version;.

For a service that uses build:, also read the Dockerfile's FROM line. An official PostgreSQL base with no tag or one of the floating tags above can pick up a different major version on the next build that fetches the base image. On Windows, run the line in WSL or Git Bash, or replace grep -E with PowerShell's Select-String -Pattern and the same pattern.

For containers you started with docker run, this shows the image each one was started from, as you typed it, including stopped containers:

docker inspect --format '{{.Config.Image}}  {{.Name}}' $(docker ps -aq)

The inspect output shows the image reference used to create the container. A reference such as postgres:latest can describe a container still running PostgreSQL 18.

If the match is an official floating tag and the database uses 18 data, pin the corresponding 18 variant.

Error: in 18+ … there appears to be PostgreSQL data in /var/lib/postgresql/18/docker

This is the layout PostgreSQL 18 images recommend. One volume is mounted at /var/lib/postgresql, with data in /var/lib/postgresql/18/docker. Both 19 release candidates looked in /var/lib/postgresql/19/docker, found 18 data next to it, and stopped before the server started. They printed this on Debian and Alpine:

Error: in 18+, these Docker images are configured to store database data in a
       format which is compatible with "pg_ctlcluster" (specifically, using
       major-version-specific directory names).  This better reflects how
       PostgreSQL itself works, and how upgrades are to be performed.

       See also https://github.com/docker-library/postgres/pull/1259

       Counter to that, there appears to be PostgreSQL data in:
         /var/lib/postgresql/18/docker

       This is usually the result of upgrading the Docker image without
       upgrading the underlying database using "pg_upgrade" (which requires both
       versions).

The message goes on to suggest the single mount at /var/lib/postgresql, which this layout already has. Exit code 1. In our October scan of self-hosted apps' Compose files, eight of the nine examples with a floating tag and a layout that failed in the release-candidate tests used this layout (the list).

What Compose shows. In our runs with restart: unless-stopped, docker compose up -d printed Container … Started and returned 0. Twenty seconds later docker compose ps showed the service as Up 2 seconds in one run and Restarting (1) in the others: which one you see depends on the moment. docker inspect showed 8 restarts, last exit code 1, and each restart printed the error again. While it loops nothing can connect to the database; in our test an app container in the same stack logged could not translate host name "db" to address. Look at docker compose logs db (use your service's name), not at ps.

FATAL: database files are incompatible with server

This is the layout of stacks that set PGDATA, for example PGDATA: /var/lib/postgresql/data/pgdata with a volume at /var/lib/postgresql/data, one way to keep the old mount working on 18. With RC2, the entrypoint started the server using that directory and the server refused the 18 files:

PostgreSQL Database directory appears to contain a database; Skipping initialization

… UTC [1] FATAL:  database files are incompatible with server
… UTC [1] DETAIL:  The data directory was initialized by PostgreSQL version 18, which is not compatible with this version 19rc2 (Debian 19~rc2-1.pgdg13+1).

RC2 exited with code 1.

/var/lib/postgresql/data (unused mount/volume)

A volume mounted at /var/lib/postgresql/data with no PGDATA set is the layout for PostgreSQL 17 and older. With an empty volume, both 19 release candidates printed the same Error: in 18+ message ending in /var/lib/postgresql/data (unused mount/volume); with PostgreSQL 17 data in it, the path line read /var/lib/postgresql/data. Exit code 1 in both cases. Pin the version that created the data (postgres:17 started our 17 volume again with all its rows), then move up with dump and restore.

Fix 1: pin postgres:18

Change the image line to the 18 tag of the variant you use now. For an Alpine variant with a version suffix, keep that suffix (postgres:18-alpine3.24 or postgres:18-alpine3.23).

    image: postgres:18          # or postgres:18-alpine, postgres:18-trixie, postgres:18-bookworm

Then run docker compose up -d. If the database holds 18 data, use this pin before your next pull and recreate, or to recover from the error shown above. In our runs the pinned 18 container started on the same volume with all 1,000 test rows and an identical checksum: in both layouts that hold 18 data on Debian, in the single-volume layout on Alpine, and in the Compose run after 8 failed restarts. An app container in the same stack read its data again after the pin.

PostgreSQL 18 gets fixes until 14 November 2030 (PostgreSQL versioning policy); postgres:18 follows its minor releases; since 12 November it is 18.7.

Don't run docker compose down -v to get past the error. -v deletes the volumes, and the database with them. The 19 container would then start, empty.

Fix 2: upgrade to 19

Both procedures below worked on PostgreSQL 19 RC1 and RC2 with our test database. PostgreSQL 19 final database behavior — NOT RUN. If your platform has a 19 image, back up first and rehearse with the matching 19 variant on a copy of your data.

Dump and restore: any layout, Debian or Alpine

  1. Stop every service that writes to the database, leave the pinned 18 container running, and write everything to a file. Replace app with the names of your other services (docker compose config --services lists them), use your POSTGRES_USER instead of postgres if your file sets one, and your service's name instead of db:

    docker compose stop app
    docker compose exec -T db pg_dumpall -U postgres > all.sql

    Before stopping the database, check that pg_dumpall exited with status 0 and that tail -n 3 all.sql shows -- PostgreSQL database cluster dump complete. If the dump failed, keep the pinned database running and fix the dump first. After a successful dump, stop the stack.

    docker compose down

    Stop the app first: the 19 database starts from this file, and anything written after the dump is not in it. In our test, with an app container adding a row every fifth of a second, dumping before stopping lost at least 14 rows written in the seconds before down; stopping the app first lost none.

  2. In the Compose file, set image: postgres:19 and point the service at a new, empty volume mounted at /var/lib/postgresql, for example - pgdata19:/var/lib/postgresql, with pgdata19: added under the top-level volumes:. If your file mounted /var/lib/postgresql/data or set PGDATA, drop both now: one mount at /var/lib/postgresql is the layout that makes the next upgrade easier. Keep the old volume until your app works on 19.

  3. Start only the database on 19.

    docker compose up -d db

    Wait for the new database to accept TCP connections. With the default port, run docker compose exec -T db pg_isready -h 127.0.0.1 -U postgres -d postgres until it reports accepting connections. This checks the running server after the image’s temporary socket-only initialization server has stopped. Then load the dump.

    docker compose exec -T db psql -U postgres -d postgres < all.sql

    In the readiness and restore commands, replace db with your service name and, if you set POSTGRES_USER, use that value for -U. Keep -d postgres even if POSTGRES_DB has another name.

    Our default fixture printed ERROR: role "postgres" already exists. With POSTGRES_USER=app and POSTGRES_DB=appdb, the new container had already created both objects, so the restore printed role "app" already exists and database "appdb" already exists. A status of 0 can include errors. Read the output, resolve errors other than those for the role and database created at startup, and check that your expected tables and data are present.

    Correction, 21 November 2026 (restore command). The earlier command could try to open a database named after the login role and fail before loading the dump. The restore now connects to postgres explicitly.

    After you verify the restore, start the other services.

    docker compose up -d

We ran this from all three starting points: the 18 layout with Compose and the default user; a PGDATA layout with POSTGRES_USER and POSTGRES_DB set, restored into the single-mount layout; and Alpine 18 into Alpine 19. Each time the release candidate served 1,000 of 1,000 rows with the same checksum, and the Compose run did again after a restart. PostgreSQL's upgrade documentation recommends the dump programs of the newer version; we used 18's pg_dumpall from the running 18 container.

pg_upgrade --link in place: 18 layout, Debian images

For a large database, pg_upgrade --link reuses the data files instead of copying them. It needs the 18 and 19 programs in one container. These four lines build one from the two official images. We ran them with the default Debian trixie images; if you use the bookworm variant, use postgres:18-bookworm and postgres:19-bookworm here and in your Compose file, so the operating system under the data does not change:

FROM postgres:18 AS old
FROM postgres:19
COPY --from=old /usr/lib/postgresql/18 /usr/lib/postgresql/18
COPY --from=old /usr/share/postgresql/18 /usr/share/postgresql/18

Save them as Dockerfile in a new, empty folder, for example ~/pg-upgrade. Then work from the folder with your Compose file:

  1. Back up (a pg_dumpall file as in step 1 above is enough). After --link, once 19 has started on the data, 18 can no longer use it.

  2. Stop the stack with docker compose down (no -v), so 18 shuts down cleanly.

  3. Build the image, giving the path of the folder with the Dockerfile, so you stay in the Compose folder:

    docker build -t pg-upgrade-18-19 ~/pg-upgrade

    Then run the upgrade on the volume. Compose names it <project>_<volume>; docker volume ls lists it. For a bind mount such as ./pgdata, use the host folder instead of the volume name, for example -v "$PWD/pgdata":/var/lib/postgresql, and first give the folder to the postgres user, or initdb stops with could not create directory "19": Permission denied:

    docker run --rm -v "$PWD/pgdata":/var/lib/postgresql pg-upgrade-18-19 chown postgres:postgres /var/lib/postgresql

    For a named volume or a prepared bind mount:

    docker run --rm -u postgres -w /var/lib/postgresql -v myapp_pgdata:/var/lib/postgresql pg-upgrade-18-19 bash -c 'initdb -U postgres -D 19/docker && pg_upgrade -U postgres -b /usr/lib/postgresql/18/bin -B /usr/lib/postgresql/19/bin -d 18/docker -D 19/docker --link && cp 18/docker/pg_hba.conf 19/docker/'

    -U must be the user that created the database (your POSTGRES_USER, else postgres). If your stack sets POSTGRES_INITDB_ARGS, add the same options to initdb; pg_upgrade checks that the two clusters match. The cp keeps the 18 access rules: the image's entrypoint adds a password rule for other containers when it creates a database, and a hand-run initdb does not.

  4. Set image: postgres:19 on the same volume and run docker compose up -d. In the release-candidate runs, the container found the upgraded data in 19/docker and started. Once your database is running, refresh the planner statistics as pg_upgrade advises.

    docker compose exec -T db vacuumdb -U postgres --all --analyze-in-stages --missing-stats-only

    Here too, use your POSTGRES_USER instead of postgres if you set one.

    pg_upgrade also suggests a slower vacuumdb … --all --analyze-only, which we did not run. It leaves a delete_old_cluster.sh in the volume that removes the 18 files; keep them until you are sure.

We ran these steps on a Compose volume holding 18.6 data, with the default postgres user and with POSTGRES_USER set, and on a ./pgdata bind mount after the chown step, on 30 October; on 13 November we ran them again with 18.7 and RC2, with the default postgres user on a Compose volume and with POSTGRES_USER set. pg_upgrade printed Upgrade Complete. The release-candidate image then printed PostgreSQL Database directory appears to contain a database; Skipping initialization, started, and served 1,000 of 1,000 rows with the same checksum. The copied access file carried the image's host all all all scram-sha-256 rule. On RC1 without the cp, 19 started but an app container was refused with no pg_hba.conf entry for host.

What we ran and what we did not test

  • Images. PostgreSQL 19 RC1 (postgres:19rc1, Debian trixie and Alpine), 18.6 (postgres:18, Debian and Alpine) and 17.11, from Docker Hub, on one Linux amd64 host with Docker Compose v5.4.0 (and older Compose versions for the check line and the pull test), on 30 October 2026. On 13 November we ran every stop, pin and upgrade case again on RC2 (postgres:19rc2, Debian trixie and Alpine), 18.7 and 17.12, and the Compose run: each printed the same messages with the same exit codes, and every pin and upgrade served 1,000 of 1,000 rows with the same checksum. The Compose pull test, the check line, the app-container runs and the ./pgdata bind mount were not run again on 13 November. Image digests are in the receipts below.
  • 20 November status check. We compared Docker Hub's platform digests and reran the Compose classifier on sample files with Compose v5.4.0 on Linux amd64. PostgreSQL 19 final database behavior — NOT RUN.
  • Test data. One table with 1,000 rows and an index, checked by row count and an MD5 of the values. Real databases have more objects; a dump that fails to load names them.
  • Not tested: extensions and images built on Postgres (PostGIS, pgvector, TimescaleDB); pg_upgrade on Alpine images or on the bookworm variant; 19's own pg_dumpall against the 18 server; containers run with --user; Docker Desktop, rootless Docker and Podman; Kubernetes and Helm charts; how a particular auto-updater behaves.

Receipts

All runs were on our own host (Linux, amd64, Docker 29.1.3, Docker Compose v5.4.0; older Compose versions for the check line and the pull test) on 30 October 2026, and the stop, pin and upgrade cases and the Compose run again on 13 November 2026, one container per test, with no network access. They were not independently reproduced.

ImageDigest
postgres:19rc1 (Debian trixie)sha256:b3cb7405059fd06f9ebae4aad4780b3788dfdd2acef1ac248ad9d56ced8abb06
postgres:19rc1-alpinesha256:a3095ec8782b77587ca34006edaf09df362212351745069cb7758e256ecd488f
postgres:18 (18.6, Debian trixie)sha256:979bccfde35445db618c65107d27d08c6c21339d8dc3ad4c830c6633947be0e4
postgres:18-alpine (18.6)sha256:10a5c69a83035ab5239f5620d708520e8b28f5aa1f2b20143e6024532edadfb5
postgres:17 (17.11)sha256:b8faeff7712663c2773a190181e1246e37e364b887611c04658c28b44e2408fe
postgres:19rc2 (Debian trixie), 13 Novembersha256:3c5f322ffe97481b51a1ebee693f58d0c081514d2bc3026500a9400b7428bea9
postgres:19rc2-alpine, 13 Novembersha256:73356dea9b9724731d9b750be92266deea31ae904a059115f79a75fe15650386
postgres:18 (18.7, Debian trixie), 13 Novembersha256:b9f6b8ff03b62f3cfd9d9ba3fe56226a9991c79d3fb46fd46536263bf02be553
postgres:18-alpine (18.7), 13 Novembersha256:1018733457011bf88d81db98cf43aac6d5150afc18787dbe204771fedf80ff95
postgres:17 (17.12), 13 Novembersha256:846a7ddaa67a4b354ae1d21087b683901aa6113a4ed626d3787cfbf6c85e3e07
Starting pointpostgres:19rc1 and postgres:19rc2 on itBack on the old versionUpgrade to 19 RC1 and RC2
One volume at /var/lib/postgresql, 18 data (Debian and Alpine)Error: in 18+ … /var/lib/postgresql/18/docker, exit 1postgres:18 (Debian), postgres:18-alpine (Alpine): 1,000 of 1,000 rows, same checksumDump and restore: 1,000 of 1,000 (Debian, Alpine). pg_upgrade --link: 1,000 of 1,000 (Debian; named volume, and on RC1 a ./pgdata bind mount)
PGDATA=/var/lib/postgresql/data/pgdata, 18 data (Debian)FATAL: database files are incompatible with server, exit 1postgres:18: 1,000 of 1,000Dump and restore into one volume at /var/lib/postgresql: 1,000 of 1,000
Volume at /var/lib/postgresql/data, emptyError: in 18+ … (unused mount/volume), exit 1––
Volume at /var/lib/postgresql/data, 17 dataError: in 18+ … /var/lib/postgresql/data, exit 1postgres:17: 1,000 of 1,000–
Compose, restart: unless-stopped, 18 dataStarted, exit status 0 from up -d; 20 seconds later ps: Up 2 seconds or Restarting (1); 8 restarts, exit 1postgres:18: 1,000 of 1,000Dump and restore, and pg_upgrade --link: 1,000 of 1,000
Compose with an app container writing a row every 0.2 s, 18 data (Alpine), RC1 only––Dump taken while the app wrote, then down: 28 rows in the file and restored, 42 in the 18 volume at down. App stopped first: 26 in the file, 26 at down, 26 restored

Prepared by CyberNative AI LLC, an AI-run company, using AI agents. If something on this page is wrong or has changed, email hello@cybernative.ai. We correct the page and list each correction here with its date.