How to Fix Postgres pg_dump Error: Server Version Mismatch Between Local and Remote

Running pg_dump against a remote database fails with a version mismatch error, even though the connection itself succeeds. PostgreSQL's dump tools are strict about client-vs-server version compatibility in one specific direction — the client tool needs to be at least as new as the server it's dumping from, and this check exists precisely to prevent silently incomplete or malformed dumps.

The Problem

A dump that should work fails immediately with a version compatibility error:

$ pg_dump -h remote-db.example.com -U app_user -d mydb -f backup.sql
pg_dump: error: aborting because of server version mismatch
pg_dump: detail: server version: 16.2; pg_dump version: 14.9

The connection itself works fine — psql against the same server succeeds without issue — it's specifically pg_dump's version check that's failing.

Why It Happens

PostgreSQL's dump format and the specific SQL syntax used to represent schema objects can change between major versions, and pg_dump needs to understand the server's version-specific features to produce a correct, complete dump. The compatibility rule is specifically one-directional: a pg_dump client can safely dump from a server running the same or an older major version, but not from a server running a newer major version than the client itself — the client simply doesn't know how to correctly represent features or syntax that didn't exist yet when it was built. This happens when:

• Your local development machine has an older PostgreSQL client installed (from your OS's default package repository, which often lags behind the latest release) than the remote managed database server (RDS, Aurora, Supabase, or a self-managed server someone else keeps updated).
• You're dumping from a database that was recently upgraded to a new major version, while your local pg_dump binary wasn't updated to match.
• Multiple PostgreSQL versions are installed on your machine, and the one currently first in your PATH happens to be an older version than intended.

The Fix

Check your local pg_dump version and the remote server's version directly:

pg_dump --version

pg_dump (PostgreSQL) 14.9

psql -h remote-db.example.com -U app_user -d mydb -c "SELECT version();"

PostgreSQL 16.2 on x86_64-pc-linux-gnu

Install a pg_dump client matching or newer than the server's major version. On Ubuntu/Debian, the official PostgreSQL APT repository provides every recent major version side by side, letting you install the specific one you need without disturbing your system's default:

sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update
sudo apt install postgresql-client-16

Run the version-specific binary explicitly rather than relying on whichever pg_dump happens to be first in your PATH:

/usr/lib/postgresql/16/bin/pg_dump -h remote-db.example.com -U app_user -d mydb -f backup.sql

On macOS with Homebrew, install the matching version and use its specific binary path similarly:

brew install postgresql@16
/opt/homebrew/opt/postgresql@16/bin/pg_dump -h remote-db.example.com -U app_user -d mydb -f backup.sql

If you'd rather avoid juggling multiple installed versions manually, running pg_dump from inside a Docker container matching the target server's version sidesteps local installation entirely and guarantees an exact version match:

docker run --rm postgres:16 pg_dump -h remote-db.example.com -U app_user -d mydb > backup.sql

Still Not Working?

If you have multiple PostgreSQL versions installed locally and the wrong one keeps getting picked up despite your efforts, check exactly which binary your shell resolves by default and adjust your PATH ordering, or use full explicit paths consistently to avoid any ambiguity:

which pg_dump

/usr/bin/pg_dump   # confirm this is actually the version you expect

ls -la /usr/bin/pg_dump

On some systems, /usr/bin/pg_dump is a symlink managed by an alternatives system (like Debian's update-alternatives) that can be redirected to point at a specific installed version explicitly:

sudo update-alternatives --config pg_dump

This presents a menu of every installed pg_dump version and lets you set the system-wide default explicitly, which is often more convenient long-term than remembering to type out full version-specific paths every time you need to dump from a newer remote server.