PostgreSQL · infra · fg-0278

postgres:latest container refuses to start with 'database files are incompatible with server'

FATAL: database files are incompatible with server

Verified 2026-10-15 · Confirmed by 0 builders · Trust 50/100

Cause

The latest tag and other tags without a major version move to each new major release, and a data directory from one major version cannot be opened by the next without pg_upgrade or a dump and restore.

Fix

Pin the major version tag for any persistent volume and upgrade on purpose with pg_upgrade or pg_dumpall.

Apply

services:
  db:
    image: postgres:17   # pin the major, never latest with a persistent volume

Affects: Any major bump of the Docker Official Image, most recently 17 to 18 in September 2025

Sources

• https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/utils/init/miscinit.c
• https://github.com/docker-library/postgres/issues/1364

claude mcp add --transport http footgun https://getfootgun.com/api/mcp