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.

Introduction & Quick Summary
pg_dump: error: server version: 16.4; pg_dump version: 15.6
pg_dump: error: aborting because of server version mismatchpg_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-clienton Ubuntu 22.04 gives 14, while the database is 16. - A container image pinned to an old tag.
postgres:15as 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.psqlfrom a different prefix, or apg_dumpwrapper in a virtualenv.
| Message | Meaning | Fix |
|---|---|---|
server version: 16.4; pg_dump version: 15.6 | Client older than server | Install a 16-or-newer client |
aborting because of server version mismatch | Same, end of output | Same |
pg_restore: error: unsupported version (1.15) in file header | pg_restore older than the dump | Match the restore tools too |
pg_dump: error: connection to server ... failed | No connection, not a version issue | Check 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.sqlpg_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.dumpKey Comparison Table
Which client can dump which server is the whole question, and it is not symmetric.
| Client major | Server 13 | Server 14 | Server 15 | Server 16 | Server 17 |
|---|---|---|---|---|---|
pg_dump 13 | Yes | No | No | No | No |
pg_dump 14 | Yes | Yes | No | No | No |
pg_dump 15 | Yes | Yes | Yes | No | No |
pg_dump 16 | Yes | Yes | Yes | Yes | No |
pg_dump 17 | Yes | Yes | Yes | Yes | Yes |
The newest client is the safe choice for reading, but the dump format must match the restore tools on the other side.
| Task | Tool | Must be at least | Notes |
|---|---|---|---|
| Logical dump | pg_dump | Server major | Newer is fine |
| Roles and tablespaces | pg_dumpall | Server major | Same rule |
| Restore custom format | pg_restore | Dump's version | Match the dump, not the source server |
| Restore plain SQL | psql | Target server major | Plain SQL is text |
| Binary replication | pg_basebackup | Server major | Physical, 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.
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# confirm which binary the shell resolves
pg_dump --version
/usr/lib/postgresql/16/bin/pg_dump --versionThe 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.dumpFor 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.
# restore into the same or a newer major
pg_restore -h new-host -U app -d app --clean --if-exists backup.dump# check the dump's version before a migration window
pg_restore --list backup.dump | head -20
pg_restore --versionThe 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.
# 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.
pg_dump -Fc --schema=public --exclude-table-data='audit_*' \
-h db.internal -U app -d app > partial.dump# dump on the server's host when the client cannot be upgraded
ssh db.internal 'pg_dump -Fc -d app' > remote.dumpRunning 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 documentationThe SQL documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit SQL work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related SQL guides
All SQL guidesPostgreSQL: canceling statement due to statement timeout
The statement was canceled by statement_timeout. Find whether the role, the pooler or the client set it, then scope a longer budget to that job.
SQLite: database is locked (SQLITE_BUSY) under concurrent writes
SQLite allows one writer. Set a busy timeout, switch to WAL, start write transactions as IMMEDIATE, and reduce to a single writer connection.
MySQL: ERROR 1040 (HY000) Too many connections
The server is out of slots because pools are too large or leaking. Read the counters, size pools against replicas, then raise the limit.
MySQL 8: Public Key Retrieval is not allowed over JDBC
The driver never sent the password. Use verified TLS, or allow key retrieval only where the network is trusted.
More in SQL
All SQL guidesThe guides filed next to this one in SQL, in library order.