pg_dump "Aborting Because of Server Version Mismatch": Match the Client to Your RDS PostgreSQL Version (Amazon Linux 2023, Docker, pg_restore)

"pg_dump: error: aborting because of server version mismatch" means your pg_dump is an older major version than the PostgreSQL server you're dumping. pg_dump can dump servers of its own major version and older, never newer, so the fix is a pg_dump at least as new as the server: check the server with SHOW server_version;, then install the matching client. On Amazon Linux 2023 that's sudo dnf swap -y postgresql15 postgresql17 (or 16, 17, 18), because AL2023 has no plain postgresql package and won't install two client versions side by side. If you can't change the machine, run pg_dump from the official Docker image of the right version. Here's the trap behind most of these errors: a backup script that worked for years breaks the day the database is upgraded, with no change on the machine running it, and the same version rule then bites again on restore, where an older pg_restore rejects a newer dump with "unsupported version (1.16) in file header". This page shows the rule, how to check both sides, the AL2023 commands, the Docker route, and the restore-side errors.

Ethan, a developer, backs up the reporting database for his friend Jake's phone repair shop every night with pg_dump, from a small Amazon Linux 2023 server, to Amazon S3. The week after he upgraded the database on Amazon RDS from PostgreSQL 15 to 17, the backup file stopped growing. The script was fine. It was the version.

New to these tools? pg_dump copies a PostgreSQL database into a file, and pg_restore or psql loads it back. Amazon RDS runs the PostgreSQL server for you, and you run these client tools on your own machine or an EC2 server.

The rule: pg_dump must be at least as new as the server

Here's what Ethan's backup log showed:

pg_dump: error: aborting because of server version mismatch
pg_dump: detail: server version: 17.11 (Debian 17.11-1.pgdg13+2); pg_dump version: 15.19

The second line says it all: a version 15 pg_dump met a version 17 server. (The part in parentheses describes how that server was built; on RDS it reads differently.) pg_dump knows the catalog of its own version and every older one, but not of versions released after it, so it refuses rather than produce a broken dump. Only the major version, the first number, matters:

So the newest client you can install is the safest choice for dumping: it handles today's server and every older one. psql is more forgiving: a version 15 psql still ran ordinary queries against the 17 server, though its backslash commands may not know about newer features.

Jake: "So the backup tool was too old to read the new database?"

Ethan: "Too old to trust itself with it. It refused instead of making a bad copy, which is the polite way to fail."

Check both versions

Before installing anything, compare the two numbers. On the machine that runs the backup:

pg_dump --version

pg_dump (PostgreSQL) 15.19

On the server side, ask PostgreSQL itself, from any client that can connect:

psql -h shop-reports.c1abcdexample.us-east-1.rds.amazonaws.com -U postgres -d shop -c "SHOW server_version;"

Or ask RDS, without connecting:

aws rds describe-db-instances --db-instance-identifier shop-reports \
  --query "DBInstances[0].EngineVersion" --output text

If the server's first number is higher than the client's, that's your error. Make a note in the upgrade checklist for the database too: every machine that runs pg_dump against it needs a matching client before the major version upgrade, not after the first failed backup.

Install the matching client on Amazon Linux 2023

AL2023 packages each PostgreSQL major version separately, and there's no plain postgresql package:

sudo dnf install -y postgresql

No match for argument: postgresql
Error: Unable to find a match: postgresql

On the October 2026 release, these client packages are available:

Each has matching -server and -contrib packages if you need them. On a fresh server, install the one that matches your database, or the newest one:

sudo dnf install -y postgresql17
pg_dump --version

Why you can't install two versions: use dnf swap

If an older client is already installed, adding a newer one fails, because both want the same program files:

Error: Transaction test error:
  file /usr/bin/clusterdb conflicts between attempted installs of postgresql17-17.11-1.amzn2023.0.1.x86_64 and postgresql15-15.12-1.amzn2023.0.1.x86_64

Replace one with the other in a single step with dnf swap:

sudo dnf swap -y postgresql15 postgresql18
pg_dump --version

pg_dump (PostgreSQL) 18.6

That's what Ethan did, choosing 18 rather than 17: one client that dumps the database today and keeps working through the next upgrade. If you need several versions on one machine, for example to test restores into older servers, use containers instead, below.

Any machine with Docker: run pg_dump from the right image

The official PostgreSQL images contain the client tools of their version, so you can run exactly the pg_dump you need without installing anything:

docker run --rm -e PGPASSWORD="$PGPASSWORD" postgres:18 \
  pg_dump -h shop-reports.c1abcdexample.us-east-1.rds.amazonaws.com -U postgres -d shop > shop.sql

The dump arrives on the container's standard output, and the > shop.sql writes it to a file on your machine. Put the password in the PGPASSWORD environment variable rather than on the command line, so it doesn't appear in your shell history, and pick the image tag to match your server: postgres:17 for PostgreSQL 17 and so on. On Amazon Linux 2023, our containers guide covers the basics, and Docker itself is one dnf install away.

The restore side: "unsupported version (1.16) in file header"

The same version rule applies when you load a dump. A custom-format dump (pg_dump -Fc) made by pg_dump 18 can't be read by an older pg_restore:

pg_restore: error: unsupported version (1.16) in file header

That's what pg_restore 15 and 16 print for a version 18 dump; pg_restore 17 reads it. The number in parentheses is the dump file's format version, not PostgreSQL's. Three ways out:

1. Use a pg_restore at least as new as the pg_dump that made the file, the same way as above.
2. Or dump in plain SQL format, without -Fc, and load it with psql -f; a plain SQL dump from pg_dump 18 of a version 17 server loaded cleanly into another version 17 server.
3. For a dump that must load into an older server, test the restore before you rely on it; newer dumps can contain syntax an older server doesn't understand.

For moving data between RDS instances in the same account, an RDS snapshot is often simpler than a dump: no client versions involved. Dumps remain the right tool for copies across accounts, to other providers, or into a local database, and for backups you keep in S3 under your own control.

A backup script that fails loudly

Ethan's real problem was that nobody noticed for a week. When pg_dump fails, it can leave an empty, 0-byte dump file behind, and a script that doesn't check exit codes uploads it and reports success. This version stops at the first failed command, refuses an empty file, and only then copies the dump to S3:

#!/bin/bash
set -euo pipefail

STAMP=$(date +%F)
FILE="/var/backups/shop-$STAMP.dump"

pg_dump -h "$DB_HOST" -U postgres -d shop -Fc -f "$FILE"
test -s "$FILE"
aws s3 cp "$FILE" "s3://shop-backups/postgres/shop-$STAMP.dump"
echo "backup ok: $FILE"

set -euo pipefail makes the script exit as soon as a command fails, test -s fails on an empty file, and the script's own exit code then tells cron or a systemd timer that something went wrong, which is what you alert on. With the old client, it now stops right after the version mismatch message, with exit code 1 and no upload. Keep PGPASSWORD in the environment of the job, or in a ~/.pgpass file readable only by the backup user, rather than in the script.

Before a PostgreSQL major version upgrade on RDS

The upgrade itself is a few clicks; the tools around it are what break. In order:

1. List every machine and job that runs pg_dump, pg_restore or psql against the database: backup scripts, CI pipelines, developers' laptops.
2. Upgrade their clients to the new major version first. A newer client works with the current, older server, so this step is safe before the upgrade.
3. Take a final backup with the newer client, and test-restore it.
4. Upgrade the database.
5. Run each backup job once by hand and check the file size and the job's exit code, not just that it ran; the script above does both.

That last step would have saved Ethan a week. If storage was the reason for the upgrade, our RDS storage guide covers autoscaling.

Troubleshooting by symptom

pg_dump: error: aborting because of server version mismatch

Your pg_dump is older than the server. Install a pg_dump of the server's major version or newer.

No match for argument: postgresql

AL2023 names packages by version. Install postgresql16, postgresql17 or postgresql18.

file /usr/bin/clusterdb conflicts between attempted installs

Two client versions can't be installed together. Use dnf swap to replace one with the other.

pg_restore: error: unsupported version (1.16) in file header

The dump was made by a newer pg_dump. Use a pg_restore at least as new, or a plain SQL dump.

Backup file is empty but the job succeeded

The script ignores pg_dump's exit code. Check it, and alert when it isn't 0.

psql works but pg_dump fails against the same server

psql tolerates newer servers; pg_dump doesn't. Upgrade the client package.

pg_dump server version mismatch: frequently asked questions

Ethan swapped the backup server's client to PostgreSQL 18, added an exit-code check that emails him on failure, and re-ran the week's missing backups by hand. Jake asked what had changed. "The database got newer," Ethan said, "and the backup tool has to be at least as new as what it's copying. Now it's newer than both."

Revision note. Written October 13, 2026, with PostgreSQL 15 to 18 on Amazon Linux 2023 release 2023.12.20261012. "A chain is only as strong as its weakest link," as the saying goes; a backup is only as new as the tool that makes it.