Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

pg_dump: server version mismatch, aborting because of server version

pg_dump refuses to read a newer server. Install a matching client, run it from a container or the server host, and match pg_restore too.

~4 min readSQL
#PostgreSQL#Backup#Migration#DevOps
A database tower at version sixteen facing a cyan client crate at fifteen, amber abort plate and matching client key

Introduction & Quick Summary

text
pg_dump: error: server version: 16.4; pg_dump version: 15.6 pg_dump: error: aborting because of server version mismatch

pg_dump refuses to dump a server whose major version is newer than the client it was built from. The check is deliberate: the server's system catalogs change between majors, and an older client cannot read the newer ones reliably. The dump is aborted before any data is written.

The four situations that produce it:

  • A distribution package that lags the server. apt install postgresql-client on Ubuntu 22.04 gives 14, while the database is 16.
  • A container image pinned to an old tag. postgres:15 as the client against a 16 server.
  • A managed service that upgraded the server. RDS, Supabase, and Cloud SQL move minor versions automatically and major versions on request or on a schedule.
  • A stale binary earlier in PATH. psql from a different prefix, or a pg_dump wrapper in a virtualenv.
MessageMeaningFix
server version: 16.4; pg_dump version: 15.6Client older than serverInstall a 16-or-newer client
aborting because of server version mismatchSame, end of outputSame
pg_restore: error: unsupported version (1.15) in file headerpg_restore older than the dumpMatch the restore tools too
pg_dump: error: connection to server ... failedNo connection, not a version issueCheck host, port, credentials

Core Mechanics, Signatures & Reproducible Setup

The rule is one-directional: a pg_dump binary can dump a server of the same major version or older, and cannot dump a newer one. A 16 client dumps a 13, 14, 15, or 16 server. A 15 client fails on a 16 server. Minor versions do not matter; 16.4 and 16.9 are both major 16.

A reproduction needs two versions:

docker run -d --name pg16 -e POSTGRES_PASSWORD=secret -p 5432:5432 postgres:16 sleep 5 # client 15 against server 16 docker run --rm --network host -e PGPASSWORD=secret postgres:15 \ pg_dump -h 127.0.0.1 -U postgres -d postgres > /tmp/db.sql
text
pg_dump: error: server version: 16.4 (Debian 16.4-1.pgdg120+1); pg_dump version: 15.8 pg_dump: error: aborting because of server version mismatch
# client 16: same command, matching major docker run --rm --network host -e PGPASSWORD=secret postgres:16 \ pg_dump -Fc -h 127.0.0.1 -U postgres -d postgres > /tmp/db.dump ls -lh /tmp/db.dump

Key Comparison Table

Which client can dump which server is the whole question, and it is not symmetric.

Client majorServer 13Server 14Server 15Server 16Server 17
pg_dump 13YesNoNoNoNo
pg_dump 14YesYesNoNoNo
pg_dump 15YesYesYesNoNo
pg_dump 16YesYesYesYesNo
pg_dump 17YesYesYesYesYes

The newest client is the safe choice for reading, but the dump format must match the restore tools on the other side.

TaskToolMust be at leastNotes
Logical dumppg_dumpServer majorNewer is fine
Roles and tablespacespg_dumpallServer majorSame rule
Restore custom formatpg_restoreDump's versionMatch the dump, not the source server
Restore plain SQLpsqlTarget server majorPlain SQL is text
Binary replicationpg_basebackupServer majorPhysical, different rules

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

Install a matching client from PGDG

Distribution repositories lag. The PostgreSQL Global Development Group repository ships the current major for Debian and Ubuntu, which is the cleanest fix on a host.

bash
sudo install -d /usr/share/postgresql-common/pgdg sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \ https://www.postgresql.org/media/keys/ACCC4CF8.asc . /etc/os-release echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] \ https://apt.postgresql.org/pub/repos/apt $VERSION_CODENAME-pgdg main" \ | sudo tee /etc/apt/sources.list.d/pgdg.list sudo apt update && sudo apt install -y postgresql-client-16
bash
# confirm which binary the shell resolves pg_dump --version /usr/lib/postgresql/16/bin/pg_dump --version

The version reported by pg_dump --version is the one that matters, not the package name.

Use a container as a portable client

A container avoids installing anything on the host and makes the version explicit in the command, which is also self-documenting in a runbook.

docker run --rm -e PGPASSWORD="$PGPASSWORD" postgres:16 \ pg_dump -Fc -h db.internal -U app -d app > backup.dump
# network mode is needed when the database listens on the host's localhost docker run --rm --network host -e PGPASSWORD="$PGPASSWORD" postgres:16 \ pg_dump -Fc -h 127.0.0.1 -U app -d app > backup.dump

For a version 17 server, change the tag to postgres:17. Nothing else in the pipeline needs to change.

Restore side has the same rule, reversed

A dump taken with a 16 client restores into 16 or newer. Restoring into an older server is not supported, and the error comes from the SQL rather than a version check.

bash
# restore into the same or a newer major pg_restore -h new-host -U app -d app --clean --if-exists backup.dump
bash
# check the dump's version before a migration window pg_restore --list backup.dump | head -20 pg_restore --version

The TOC list also shows whether the dump is custom or directory format, which determines whether psql -f can read it at all.

Managed services and the pg_upgrade path

A managed service decides when the server major moves. The client used by a backup job must be part of the same change, and a scheduled task that pins a client version fails on the day of the upgrade.

bash
# read what the server reports, before planning the client psql "$DATABASE_URL" -Atc "select current_setting('server_version'), current_setting('server_version_num')"
# pin the client to the major the server reports PG_MAJOR=$(psql "$DATABASE_URL" -Atc "select current_setting('server_version_num')" | cut -c1-2) docker run --rm -e PGPASSWORD="$PGPASSWORD" "postgres:${PG_MAJOR}" \ pg_dump -Fc -h "$PGHOST" -U "$PGUSER" -d "$PGDATABASE" > "backup-$(date +%F).dump"

Deriving the tag from server_version_num keeps the job correct across an upgrade, and the value is cheap to log.

Partial dumps and the same version check

--schema, --table, and --exclude-table-data do not bypass the version check. The abort happens before the client inspects the catalog.

bash
pg_dump -Fc --schema=public --exclude-table-data='audit_*' \ -h db.internal -U app -d app > partial.dump
bash
# dump on the server's host when the client cannot be upgraded ssh db.internal 'pg_dump -Fc -d app' > remote.dump

Running pg_dump on the database host is often the quickest correct answer, because the server package installs a matching client.

Common Compilation/Runtime Mistakes & Version Gotchas

Comparing minor versions. 16.4 against 16.1 is not a mismatch. Only the major digit is checked, so a message showing the same major digit with different minors is a different error.

Upgrading the client without the restore tools. pg_dump 16 with pg_restore 15 fails at restore time with unsupported version (1.16) in file header, which is the same mistake one step later.

Assuming pg_dumpall is exempt. It has the same check and the same fix.

Trusting psql --version when a wrapper is installed. A virtualenv or a language runtime sometimes bundles an old client. command -v pg_dump and pg_dump --version together settle which binary runs.

Using pg_upgrade for a logical move. pg_upgrade is for in-place major upgrades with both binaries installed; it is not a way to dump across versions and does not accept a remote -h.

Version notes. The check has existed since PostgreSQL 9.x and applies through 17. pg_dump --no-synchronized-snapshots was replaced by --no-sync-style options over time; --snapshot support and parallel dump (-j) require the directory format. PostgreSQL 17 changed the default output of some pg_dump options, so read the release notes before scripting against a version change.

Fix order: read the two versions in the message, install or run a client with the server's major version, then verify the restore tools match the dump. A quick check of the connection settings before the version hunt is worth the minute, and the env reader shows whether PGHOST or PGPORT is pointing at a different server than the one you think, while the SQL formatter keeps the pg_restore --list output and catalog queries readable.

Official references: pg_dump and Upgrading a PostgreSQL cluster.

Official references

primary documentation

The SQL documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit SQL work — they run entirely in this browser tab, so nothing you paste leaves your device.

All SQL guides

More in SQL

All SQL guides

The guides filed next to this one in SQL, in library order.