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 barepostgres) andpostgres:trixiematchedpostgres:19andpostgres:19-trixie, respectively, onlinux/amd64,linux/386,linux/arm/v5,linux/arm/v7,linux/arm64/v8,linux/ppc64leandlinux/s390x.postgres:alpine,postgres:alpine3.24andpostgres:alpine3.23matched their 19 counterparts onlinux/amd64,linux/386,linux/arm/v6,linux/arm/v7,linux/arm64/v8,linux/ppc64leandlinux/s390x.postgres:bookwormmatchedpostgres:19-bookwormon all five listed platforms (linux/amd64,linux/386,linux/arm/v7,linux/arm64/v8andlinux/ppc64le).- On
linux/riscv64,latest,trixieand 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/. Both 19 release candidates looked in /var/, 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/ with a volume at /var/, 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/ 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/; with PostgreSQL 17 data in it, the path line read /var/. 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-bookwormThen 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
Stop every service that writes to the database, leave the pinned 18 container running, and write everything to a file. Replace
appwith the names of your other services (docker compose config --serviceslists them), use yourPOSTGRES_USERinstead ofpostgresif your file sets one, and your service's name instead ofdb:docker compose stop app docker compose exec -T db pg_dumpall -U postgres > all.sqlBefore stopping the database, check that
pg_dumpallexited with status 0 and thattail -n 3 all.sqlshows-- 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 downStop 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.In the Compose file, set
image: postgres:19and point the service at a new, empty volume mounted at/var/lib/postgresql, for example- pgdata19:/, withvar/ lib/ postgresql pgdata19:added under the top-levelvolumes:. If your file mounted/var/or setlib/ postgresql/ data PGDATA, drop both now: one mount at/var/lib/postgresqlis the layout that makes the next upgrade easier. Keep the old volume until your app works on 19.Start only the database on 19.
docker compose up -d dbWait 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 postgresuntil it reportsaccepting 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.sqlIn the readiness and restore commands, replace
dbwith your service name and, if you setPOSTGRES_USER, use that value for-U. Keep-d postgreseven ifPOSTGRES_DBhas another name.Our default fixture printed
ERROR: role "postgres" already exists. WithPOSTGRES_USER=appandPOSTGRES_DB=appdb, the new container had already created both objects, so the restore printedrole "app" already existsanddatabase "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
postgresexplicitly.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/18Save them as Dockerfile in a new, empty folder, for example ~/pg-upgrade. Then work from the folder with your Compose file:
Back up (a
pg_dumpallfile as in step 1 above is enough). After--link, once 19 has started on the data, 18 can no longer use it.Stop the stack with
docker compose down(no-v), so 18 shuts down cleanly.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-upgradeThen run the upgrade on the volume. Compose names it
<project>_<volume>;docker volume lslists it. For a bind mount such as./pgdata, use the host folder instead of the volume name, for example-v "$PWD/, and first give the folder to thepgdata":/ var/ lib/ postgresql postgresuser, orinitdbstops withcould not create directory "19": Permission denied:docker run --rm -v "$PWD/pgdata":/var/lib/postgresql pg-upgrade-18-19 chown postgres:postgres /var/lib/postgresqlFor 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/'-Umust be the user that created the database (yourPOSTGRES_USER, elsepostgres). If your stack setsPOSTGRES_INITDB_ARGS, add the same options toinitdb;pg_upgradechecks that the two clusters match. Thecpkeeps the 18 access rules: the image's entrypoint adds a password rule for other containers when it creates a database, and a hand-runinitdbdoes not.Set
image: postgres:19on the same volume and rundocker compose up -d. In the release-candidate runs, the container found the upgraded data in19/dockerand started. Once your database is running, refresh the planner statistics aspg_upgradeadvises.docker compose exec -T db vacuumdb -U postgres --all --analyze-in-stages --missing-stats-onlyHere too, use your
POSTGRES_USERinstead ofpostgresif you set one.pg_upgradealso suggests a slowervacuumdb … --all --analyze-only, which we did not run. It leaves adelete_old_cluster.shin 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./pgdatabind 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_upgradeon Alpine images or on thebookwormvariant; 19's ownpg_dumpallagainst 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.
| Image | Digest |
|---|---|
postgres:19rc1 (Debian trixie) | sha256:b3cb7405059fd06f9ebae4aad4780b3788dfdd2acef1ac248ad9d56ced8abb06 |
postgres:19rc1-alpine | sha256: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 November | sha256:3c5f322ffe97481b51a1ebee693f58d0c081514d2bc3026500a9400b7428bea9 |
postgres:19rc2-alpine, 13 November | sha256:73356dea9b9724731d9b750be92266deea31ae904a059115f79a75fe15650386 |
postgres:18 (18.7, Debian trixie), 13 November | sha256:b9f6b8ff03b62f3cfd9d9ba3fe56226a9991c79d3fb46fd46536263bf02be553 |
postgres:18-alpine (18.7), 13 November | sha256:1018733457011bf88d81db98cf43aac6d5150afc18787dbe204771fedf80ff95 |
postgres:17 (17.12), 13 November | sha256:846a7ddaa67a4b354ae1d21087b683901aa6113a4ed626d3787cfbf6c85e3e07 |
| Starting point | postgres:19rc1 and postgres:19rc2 on it | Back on the old version | Upgrade to 19 RC1 and RC2 |
|---|---|---|---|
One volume at /var/lib/postgresql, 18 data (Debian and Alpine) | Error: in 18+ … /var/, exit 1 | postgres:18 (Debian), postgres:18-alpine (Alpine): 1,000 of 1,000 rows, same checksum | Dump 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=, 18 data (Debian) | FATAL: database files are incompatible with server, exit 1 | postgres:18: 1,000 of 1,000 | Dump and restore into one volume at /var/lib/postgresql: 1,000 of 1,000 |
Volume at /var/, empty | Error: in 18+ … (unused mount/volume), exit 1 | – | – |
Volume at /var/, 17 data | Error: in 18+ … /var/, exit 1 | postgres:17: 1,000 of 1,000 | – |
Compose, restart: unless-stopped, 18 data | Started, exit status 0 from up -d; 20 seconds later ps: Up 2 seconds or Restarting (1); 8 restarts, exit 1 | postgres:18: 1,000 of 1,000 | Dump 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.