incompatible data directory 🐘 PostgreSQL

FATAL: database files are incompatible with server — The data directory was initialized by PostgreSQL version 15, which is not compatible with this version 16

A newer (or older) PostgreSQL major version was started on an existing data directory.

Seen on: PostgreSQL

Meaning

Major versions have different on-disk formats. Bumping the Docker image tag (postgres:15 → postgres:16) on an existing volume triggers this.

Common causes

  • Docker image tag upgraded on the same volume
  • OS package upgrade without pg_upgrade

⚡ Quick fix

  1. Go back to the original version to start the server
  2. Upgrade with pg_upgrade or dump/restore into the new version
  3. Pin major versions in Docker tags

Detailed fix by platform

Docker

  1. docker run --rm -v pgdata:/var/lib/postgresql/data postgres:15 pg_dumpall … then restore into a postgres:16 volume

How to diagnose

  1. Versions — Data dir version vs server version
  2. Recent change — Did it start after a deploy, upgrade, or configuration change? Compare with the last working version.

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.