(opens in a new tab)

pg_dump Server Version Mismatch: How to Fix It

November 8, 2026 by Chat2DB Team

The database was upgraded last week, and today the nightly backup job failed with this:

pg_dump: error: aborting because of server version mismatch
pg_dump: detail: server version: 18.6; pg_dump version: 15.19

The detail line gives the cause. The server runs PostgreSQL 18, and the pg_dump binary that the job called belongs to PostgreSQL 15. pg_dump refuses to dump a server that is newer than itself, so it stops before reading anything.

This guide explains the rule pg_dump applies, how to find which binary your system really runs, and how to fix it on Linux packages, macOS, Docker and GUI tools. Every message below comes from PostgreSQL 14.24, 15.19 and 18.6.

The Rule pg_dump Follows

pg_dump has to read the system catalogs to find tables, types, functions and everything else. Each major release changes those catalogs, adding columns and object types that older code does not know about. A pg_dump 15 talking to an 18 server could miss objects or write a dump that does not restore. So it refuses.

The rule in the source code is short. pg_dump 18 accepts any server from 9.2 up to any minor release of 18:

• A newer client with an older server works. pg_dump 18 dumped our 14.24 server without complaint, and the file header recorded both versions:

-- Dumped from database version 14.24
-- Dumped by pg_dump version 18.6

• Any minor version within the same major works. pg_dump 18.6 can dump an 18.1 or 18.9 server.
• An older client with a newer major fails with the error above.
• A server older than 9.2 fails with the same error from current clients, because support for those versions was removed.

pg_dumpall applies the same check. Older releases print the two lines in a different order:

pg_dumpall: error: server version: 18.6; pg_dumpall version: 14.24
pg_dumpall: error: aborting because of server version mismatch

psql is more relaxed. A psql 15 connected to our 18 server and ran queries. Interactive sessions show a warning that some backslash commands may not work, but nothing stops you. That is why many people only notice the version gap when the backup job fails.

Step 1: Find Out Which Versions You Have

Check both sides. On the server, run:

SELECT version();
SHOW server_version;

On the machine that runs the dump, check the binary the job actually calls, not the one you think it calls:

which pg_dump
pg_dump --version

pg_dump (PostgreSQL) 15.19

If the backup runs from cron, a systemd timer or a CI pipeline, run these commands in the same environment. Those jobs often have a different PATH from your interactive shell. The fix is always the same: get a pg_dump whose major version is at least the server's.

Fix on Debian and Ubuntu

Install the client for the server's version from the PostgreSQL apt repository (PGDG). Client packages for several versions can live side by side:

sudo apt install postgresql-client-18

Debian's pg_dump command is a wrapper (pg_wrapper). It picks a version based on the local cluster it thinks you mean, or the newest installed client when there is no local cluster. On a server that still has an old local cluster, the wrapper may choose the old binary. Bypass it by calling the binary directly:

/usr/lib/postgresql/18/bin/pg_dump -h db.internal -U backup -Fc -f shop.dump shop

Or tell the wrapper which version to use:

PGCLUSTER=18/main pg_dump -Fc -f shop.dump shop

Using the full path in backup scripts is safer than relying on the wrapper's choice.

Fix on RHEL, Rocky and Alma Linux

The PGDG yum and dnf packages install each version under its own directory. Install the client and call it by path:

sudo dnf install postgresql18
/usr/pgsql-18/bin/pg_dump --version

The system pg_dump on PATH often comes from the distribution's own, older package. Check with which pg_dump after installing.

Fix on macOS

With Homebrew, either install the full versioned formula or just the client libraries, which include pg_dump, pg_restore and psql:

brew install libpq
$(brew --prefix libpq)/bin/pg_dump --version

libpq is keg-only, so it does not replace whatever is on your PATH. Use the full path, or add $(brew --prefix libpq)/bin to the front of your PATH. If you also have postgresql@14 or postgresql@15 installed and linked, they win until you change the PATH order.

Postgres.app bundles a separate binary directory for each server version. Use the one that matches the server you are dumping, or the newest one.

Fix With Docker

When the database runs in a container, the easiest way to get a matching client is to use the one inside the server container:

docker exec -t db pg_dump -U postgres -Fc shop > shop.dump

The -t flag allocates a terminal, which can corrupt binary output on some setups. For custom-format dumps it is safer to write the file inside the container and copy it out:

docker exec db pg_dump -U postgres -Fc -f /tmp/shop.dump shop
docker cp db:/tmp/shop.dump .

For a remote server, run a throwaway container of the right version:

docker run --rm -v "$PWD":/out postgres:18 \
  pg_dump -h db.internal -U backup -Fc -f /out/shop.dump shop

Match the image tag to the server's major version or newer. A postgres:latest image is fine today, but it moves when a new major comes out, so pin a version in scripts.

Fix in GUI Tools

Desktop tools that offer backup buttons usually call a local pg_dump binary. If the tool shipped with an older one, or you pointed it at an old installation, you get the same mismatch error inside the tool. Look for a setting called something like "binary path" or "local client" and point it at the directory of a current client, such as /usr/lib/postgresql/18/bin or the Homebrew libpq directory. For quick exports of a single table or query result, a client such as Chat2DB (opens in a new tab) can export data directly without calling pg_dump. For full logical backups, a matching pg_dump is still the tool to use.

Confirm the Fix Worked

After switching clients, take a dump and read its header. pg_restore -l on a custom-format file prints both versions near the top:

pg_restore -l shop.dump | head -12

;     Dumped from database version: 18.6
;     Dumped by pg_dump version: 18.6

For a plain SQL dump, the same two lines are comments at the top of the file. Seeing the expected client version there proves the job used the new binary, not just that it stopped failing. If the backup job runs on a schedule, check the next scheduled run, not only a manual test, because scheduled jobs often run with a different PATH.

Do Not Downgrade the Dump Format by Hand

Some old forum answers suggest editing the version check, using a --ignore-version flag, or patching the binary. --ignore-version was removed many releases ago, and patching around the check gives you a backup that may be missing objects or may not restore. Install the right client instead. It takes a minute.

The opposite case, a dump file that is too new for your pg_restore, is a different error: unsupported version (1.16) in file header. It means the restore side needs a newer client. Our guide to pg_restore unsupported version covers it, and the pg_dump File Inspector (opens in a new tab) tells you which client versions can read a given dump.

Make Backups Survive the Next Upgrade

This error is common right after a major upgrade, for example when moving off PostgreSQL 14 before its end of life on November 12, 2026. A few habits prevent it:

1. Upgrade clients first. A new pg_dump works with old servers, so put the newest client on backup hosts before you upgrade any server.
2. Call binaries by full path in scripts, for example /usr/lib/postgresql/18/bin/pg_dump, so a PATH change or a wrapper decision cannot switch versions.
3. Check exit codes. pg_dump exits with status 1 on this error. A cron job that ignores the exit code can produce an empty file every night for weeks. Fail loudly instead:

#!/bin/bash
set -euo pipefail
/usr/lib/postgresql/18/bin/pg_dump -h db.internal -U backup -Fc -f "/backups/shop-$(date +%F).dump" shop

4. Test restores. Restore last night's backup into a scratch database every week. A backup that was never restored is a guess.

Our pg_dump command generator (opens in a new tab) builds the command line for common backup cases, and the pg_dump and pg_restore guide explains the formats and options in detail.