Scenario
A DBA is upgrading a production PostgreSQL cluster from PG13 to PG16 using pg_upgrade. The upgrade fails with one or more of these errors:
"database cluster was not shut down cleanly" — postmaster.pid still exists in the old data directory, meaning the old cluster was not stopped before pg_upgrade ran."extension 'uuid-ossp' is not installed in new cluster" — extensions present in the old cluster are absent from the new PostgreSQL installation’s $libdir."catalog incompatibility" — contrib modules or shared preload libraries differ between the old and new installations, causing pg_upgrade --check to report mismatches.
Until all three classes of failure are resolved, the new cluster will not start and the old cluster remains unchanged.
How to Identify
| Condition |
Signal |
| Old cluster still running |
pg_upgrade prints "There is a postmaster running" or postmaster.pid exists in $PGDATA |
| Extension missing in new install |
pg_upgrade --check lists missing extensions under "Checking for presence of required libraries" |
| Contrib/library mismatch |
pg_upgrade --check reports "Your installation references loadable libraries that do not exist" |
| Data checksum mismatch |
pg_upgrade aborts: "old and new pg_controldata checksum settings are inconsistent" |
| WAL archive not migrated |
pg_upgrade completes but archived WAL from old cluster is silently left behind |
Run pg_upgrade --check before touching the old cluster to surface all issues without making any changes.