Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

pg_dump refuses to run: server version is newer than pg_dump

Errorpg_dump: error: aborting because of server version mismatch

Short answer

pg_dump will not dump a server whose major version is newer than its own. Your PATH finds an older pg_dump than the server. Install the client package for the server's major version, call that binary by full path, or run pg_dump on the server host.

  • Applies to PostgreSQL 16, PostgreSQL 17, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the server's version with the pg_dump that your shell actually runs.

    psql -h dbhost -U appuser -d appdb -Atc "SHOW server_version"
    which -a pg_dump; pg_dump --version
  2. 2Match what you see, then jump to its fix

    1. 1The detail line shows a server version with a higher major number than pg_dumpThe client tools are an older major version than the serverFix
    2. 2which -a shows more than one pg_dumpSeveral PostgreSQL versions are installed and PATH picks the old oneFix
    3. 3You cannot or do not want to install new client tools on this machineDump on the server host insteadFix

What does the error look like?

  • pg_dump: error: aborting because of server version mismatch
  • pg_dump: detail: server version: 17.2; pg_dump version: 14.13

Cause 1 of 3

The client tools are an older major version than the server

1Check

pg_dump refuses servers newer than itself instead of risking an invalid dump. Its output can load into newer servers, but it cannot read from them.

pg_dump --version

2Fix

Install the client package of the server's major version from the PostgreSQL apt repository, then run that version's binary.

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-client-17
/usr/lib/postgresql/17/bin/pg_dump -h dbhost -U appuser -Fc -f appdb.dump appdb

3Verify

The dump file is created and pg_restore can list it.

pg_restore --list appdb.dump | head

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 3

Several PostgreSQL versions are installed and PATH picks the old one

1Check

The first pg_dump on PATH runs, regardless of the server you are dumping.

which -a pg_dump

2Fix

Call the right binary by its full path, or put that directory first on PATH for the session.

# Debian/Ubuntu package layout
/usr/lib/postgresql/17/bin/pg_dump --version
export PATH=/usr/lib/postgresql/17/bin:$PATH

3Verify

pg_dump --version reports the server's major version.

pg_dump --version

Confirmed by postgresql.org

Did this fix it?

Cause 3 of 3

Dump on the server host instead

1Check

pg_dump that ships with the server is always the same major version as the server.

ssh dbhost 'pg_dump --version'

2Fix

Run pg_dump on the server host and copy the file, which the custom format keeps compressed and restorable with pg_restore.

ssh dbhost 'pg_dump -U appuser -Fc appdb' > appdb.dump

3Verify

The file is not empty and lists its contents.

pg_restore --list appdb.dump | head

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Upgrade the client tools together with the server (same major version, or newer).
  • In backup scripts, call pg_dump by full path instead of relying on PATH.
  • Restore a test dump after each major upgrade.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.