Here's an error that stops a lot of first-time Supabase backup setups cold:
pg_dump: error: server version mismatch
pg_dump: detail: server version: 17.x, pg_dump version: 16.x
No dump is produced. The good news: this one is honest about what's wrong, and the fix takes about three lines. The annoying part is where the fix has to go.
Why pg_dump refuses
pg_dump has a hard rule: it will not dump a server that is newer than itself. This isn't pedantry. A dump has to describe everything in the database — system catalogs, object types, syntax — and an older client can't be trusted to understand a newer server's internals. Rather than produce a subtly wrong backup, it refuses outright.
The mismatch is easy to walk into right now:
- Supabase runs PostgreSQL 17.
-
GitHub-hosted runners (
ubuntu-latest) ship a PostgreSQL client that tops out at 16 from Ubuntu's default repositories. The same is true of a lot of local installs — Debian and Ubuntu stable lag the server world by a version or two.
So the most common setup — Supabase project, GitHub Actions cron, pg_dump — hits this on the very first run, before any of the subtler backup traps get a chance.
Check your versions first
Before changing anything, confirm which side is which:
# Your client
pg_dump --version
# The server (run against your Supabase connection string)
psql "$SUPABASE_DB_URL" -t -c "SHOW server_version;"
If the client's major version is lower than the server's, that's your whole problem. (Client newer than server is fine — pg_dump 17 will happily dump a 15 or 16 server.)
The fix in GitHub Actions: install the 17 client from PGDG
postgresql-client-17 isn't in Ubuntu's default repos, so a plain apt-get install can't find it. You add PostgreSQL's official apt repository (PGDG) first:
- name: Install PostgreSQL 17 client
run: |
curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc \
| sudo gpg --dearmor -o /usr/share/keyrings/postgresql.gpg
. /etc/os-release
echo "deb [signed-by=/usr/share/keyrings/postgresql.gpg] https://apt.postgresql.org/pub/repos/apt ${VERSION_CODENAME}-pgdg main" \
| sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update -qq
sudo apt-get install -y -qq postgresql-client-17
Put this step before your dump step, and verify what you actually got — runner images change over time, and you want the failure to be loud if the 17 client ever goes missing:
- name: Verify pg_dump version
run: pg_dump --version # must print 17.x
The same fix locally, without touching your system install
If the mismatch is on your own machine and you don't want to upgrade your system PostgreSQL, borrow the client from the official Docker image for a one-off dump:
docker run --rm postgres:17 \
pg_dump "postgres://postgres.<ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres" \
--format=custom > backup.dump
(The postgres:17 image's client always matches its major version. Note the session-pooler connection string — dumping through the transaction pooler on port 6543 fails for unrelated reasons.)
Make it not come back
Version mismatches are a recurring hazard, not a one-time setup step: Supabase will eventually move to PostgreSQL 18, and runner images drift on their own schedule. Two habits keep this from silently breaking a backup pipeline later:
-
Pin and assert. Install the client version explicitly (as above) and assert
pg_dump --versionin the workflow. If the assertion fails, the run fails loudly — which is what you want from a backup job. - Fail noisily in general. A backup workflow that errors is an inconvenience; a backup workflow that silently stops is a data-loss story. Whatever you use to run dumps, make sure a failed run notifies a human.
That's the whole trap: three lines of repository setup, discovered — like most backup lessons — at the exact moment you first rely on the thing.
This is the second of five traps I hit building a weekly pg_dump → Cloudflare R2 backup for a Supabase Free project. The minimal working setup is free on GitHub as supabase-free-backup-lite; the hardened version — including a pre-flight check that catches this version mismatch before the run — is the Supabase Free-Tier Backup Kit.
Top comments (0)