About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
These two errors come from the same mistake: the pg_dump or pg_restore program you ran is older than the thing it was asked to handle. pg_dump refuses a server of a newer major version than itself, and pg_restore refuses an archive in a format newer than it can read, which happens when a newer pg_dump wrote the file. The fix is to run the tools from the same or a newer major version, which on a machine with several PostgreSQL versions often means calling the right binary by its full path. A third message, "input file appears to be a text format dump. Please use psql.", is a different problem: you gave pg_restore a plain-text dump.
What the error means
Server version mismatch. The PostgreSQL documentation states the rule: "pg_dump cannot dump from PostgreSQL servers newer than its own major version; it will refuse to even try, rather than risk making an invalid dump." It can dump from older servers, and "currently, servers back to version 9.2 are supported" (pg_dump). In the PostgreSQL 18 source, the check in the shared archiver connection code compares the server's version number with the tool's own and, if the server's major version is outside the range the tool accepts, prints aborting because of server version mismatch followed by server version: %s; %s version: %s and exits (pg_backup_db.c). For pg_dump in that source, the minimum is set as version 9.2 and the maximum as any minor release of the tool's own major version (pg_dump.c).
Unsupported version in file header. Archive-format dumps (custom, directory and tar) carry an archive version number in their header. pg_restore checks it against the newest it can read. In the PostgreSQL 18 source, ReadHead() rejects an archive when the version is below the oldest known or above K_VERS_MAX, with the message unsupported version (%d.%d) in file header (pg_backup_archiver.c). K_VERS_MAX is the newest format the tool can read. In the source headers, PostgreSQL 16's branch sets the current archive version to 1.15, and the 17 and 18 branches set it to 1.16, with 1.16 described as adding "BLOB METADATA entries and multiple BLOBS, relkind" (REL_16, REL_17, REL_18). So a pg_restore from the 16 branch asked to read an archive made by the 17 or 18 pg_dump reads 1.16 against a maximum of 1.15, and stops. The two numbers in brackets in your message show the archive version of the file.
Text format dump. pg_dump writes a plain-text SQL script by default (-F p), and the documentation says: "To restore from such a script, feed it to psql", while archive formats go to pg_restore. The source prints input file appears to be a text format dump. Please use psql. when pg_restore is given a plain script. A file that is empty, cut short or not an archive at all gives the neighbouring message input file does not appear to be a valid archive (too short?).
Direction matters. The documentation says the output "can be expected to load into PostgreSQL server versions newer than pg_dump's version", but "it is not guaranteed that pg_dump's output can be loaded into a server of an older major version". A newer dump into an older server may need manual editing.
Example (illustrative): a workstation has PostgreSQL 15 client tools. Running pg_dump against server db01, which runs a 17-series release, prints aborting because of server version mismatch and server version: 17.5; pg_dump version: 15.8. The message layout follows the source.
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
pg_dump is an older major version than the server |
aborting because of server version mismatch, with both versions shown |
Compare pg_dump --version with the server's version() |
| Several PostgreSQL versions installed and the wrong binary runs first | Same message, although a newer pg_dump is installed | Run the binary by full path and compare |
pg_restore is older than the pg_dump that wrote the archive |
unsupported version (1.x) in file header |
Compare pg_restore --version with the pg_dump that made the file |
Plain-text dump given to pg_restore |
input file appears to be a text format dump. Please use psql. |
Open the file; it is an SQL script |
| File truncated or not a dump | input file does not appear to be a valid archive (too short?) |
Check the file size against the original |
| Server older than the tool supports | Same mismatch message | Server below 9.2 for the PostgreSQL 18 tools |
Prove the cause before changing anything
All of these only read. The syntax follows the PostgreSQL documentation and has not been run.
- Ask the server its version.
version()returns a string describing the server's version:
SELECT version();
- Ask each tool its version. Both programs document
-Vand--version:
pg_dump --version
pg_restore --version
- Find which binaries exist. On Debian-family systems,
pg_wrapperis run "only as a link to names which correspond to PostgreSQL programs in /usr/lib/postgresql/version/bin" (pg_wrapper(1), bookworm). It selects the version from, in descending order,--host,--cluster(formversion/cluster),PGHOST, thePGCLUSTERvariable, a port,~/.postgresqlrc, and/etc/postgresql-common/user_clusters. After those, "If only one cluster exists on the local system, that one will be selected. If several clusters exist, the one listening on the default port 5432 will be selected." On a host with several versions installed, this is why the wrongpg_dumpversion can run. Calling/usr/lib/postgresql/<version>/bin/pg_dump --versionremoves the guesswork. Other platforms install elsewhere, so check where your package puts its binaries. - Read the archive header.
pg_restore --list <file>lists the table of contents. If it fails with the unsupported-version message, the tool is too old for that file. If it fails with the text-format message, the file is an SQL script.
Fix
Mismatch on pg_dump. Install client tools from the same or a newer major version than the server, and run them. The upgrade documentation recommends using the newer version's dump programs anyway: "It is recommended that you use the pg_dump and pg_dumpall programs from the newer version of PostgreSQL" (Upgrading a PostgreSQL cluster). You do not have to upgrade the server. The tools are enough, and the documentation says current releases of the dump programs read data from any server back to 9.2.
Unsupported version in file header. Restore with a pg_restore of at least the major version of the pg_dump that created the archive. If the file was made by 17 and the target server is 16, a 17 pg_restore can read it, but the documentation notes that loading a newer dump into an older server is not guaranteed and may need manual editing. In that case, take a fresh dump from the source with a pg_dump the target can accept, and consider --quote-all-identifiers for cross-version cases, as recommended on the pg_dump page. A new dump reads the whole source database, so do it at a time the source can bear.
Text dump given to pg_restore. Load it with psql, which the documentation names for plain scripts. The -d and -f options select the database and the file:
psql --dbname=newdb --file=dump.sql
Alternatively, make future dumps in an archive format with --format=custom so pg_restore can select and reorder items and, for custom and directory formats, restore in parallel.
Taking and restoring an archive. The documented options are -F/--format, -f/--file, -h, -p, -U, a database name, and on restore -d/--dbname and -C/--create:
pg_dump --format=custom --file=db.dump --host=db01 --port=5432 --username=backup salesdb
pg_restore --dbname=newdb db.dump
With -C, the database named by -d is used only for the initial DROP and CREATE, and data is restored into the database name that appears in the archive. A restore into an existing database can overwrite objects, so restore into a new, empty database for verification.
Side-by-side servers. For a migration, the documentation describes installing the new server in a different directory and running both in parallel on different ports, with pg_dumpall -p 5432 | psql -d postgres -p 5433. That example moves a whole cluster, so treat it as a pattern for a planned migration, not a quick fix for a single dump.
Confirm the fix
pg_dumpcompletes without the mismatch message, and the file is non-empty.pg_restore --listruns on the file and prints a table of contents.- Restore into a new, empty database on a test server and check the objects and row counts you care about. A dump that restores is proof; a dump that completed is not.
- If roles, extensions or tablespaces matter, remember a single-database dump does not carry roles; see the article on logical dumps.
What to watch afterwards
- Pin the tool version in backup scripts by full path, and log
--versionin the job output. - When the server is upgraded, upgrade the backup host's client tools in the same change. Do this before the first dump after the upgrade.
- Keep the version of the
pg_dumpthat wrote each archive in the backup catalogue name or metadata, so the restore host knows what it needs. - The mismatch check in the PostgreSQL 18 source accepts any minor release of the tool's own major version, so the rule to track is the major version.
Read next
Related articles you may want next.
- Backup & RecoveryA PostgreSQL Dump Restored with Missing Roles or Extensions: Check the Recovery SetInventory database content, cluster-wide objects and extension packages needed for a usable logical restore.Read article
- Backup & RecoveryPostgreSQL physical backups: pg_basebackup, incremental backups and pg_combinebackupHow PostgreSQL physical backups work: pg_basebackup, WAL options, incremental backups from version 17, pg_combinebackup chains and pg_verifybackup checks.Read article
- Backup & RecoveryPostgreSQL point-in-time recovery: recovery targets, timelines and choosing the right branchHow PostgreSQL point-in-time recovery chooses a stop point: recovery targets, inclusive stops, pausing to check, restore points and timeline branches.Read article
Risks and limits
- These commands follow the PostgreSQL documentation and have not been run or lab-tested.
- The error messages and the 1.15 and 1.16 archive versions come from the project's source on the REL_16, REL_17 and REL_18 stable branches (project's GitHub mirror, 16 November 2026). The messages are not in the user documentation and may change between releases. The prefix printed before them (for example
pg_dump: error:) varies by version. - The source check read for the mismatch message is in code shared by the dump and restore tools. How
pg_restoretreats the version of the target server is not covered here. - The mapping of the 16, 17 and 18 branches to archive versions is for those branches only. Earlier and later releases may differ.
- The
pg_wrapperbehaviour described is for the Debian bookworm manual page (package 248, 14 March 2023). Newer package versions may differ.
Sources
- pg_dump — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
- pg_restore — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
- psql — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
- Upgrading a PostgreSQL Cluster — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
- Information functions (version()) — PostgreSQL Global Development Group, PostgreSQL 18.7 documentation, date not shown, accessed 16 November 2026
- pg_backup_db.c, REL_18_STABLE — PostgreSQL source (GitHub mirror), date not shown, accessed 16 November 2026
- pg_dump.c, REL_18_STABLE — PostgreSQL source (GitHub mirror), date not shown, accessed 16 November 2026
- pg_backup_archiver.c, REL_18_STABLE — PostgreSQL source (GitHub mirror), date not shown, accessed 16 November 2026
- pg_backup_archiver.h, REL_16_STABLE — PostgreSQL source (GitHub mirror), date not shown, accessed 16 November 2026
- pg_backup_archiver.h, REL_17_STABLE — PostgreSQL source (GitHub mirror), date not shown, accessed 16 November 2026
- pg_backup_archiver.h, REL_18_STABLE — PostgreSQL source (GitHub mirror), date not shown, accessed 16 November 2026
- pg_wrapper(1), Debian bookworm, postgresql-client-common 248 — Debian, 14 March 2023, accessed 16 November 2026
This article was originally published on .