immich-app/immich · critical · UnsupportedPostgresError

Unsupported PostgreSQL version

Error message

Unsupported PostgreSQL version: ${databaseVersion}

What it means

During a database restore, the service parses the PostgreSQL server version and requires it to satisfy >=14.0.0 <19.0.0 with a known major version. If the major version or semver cannot be determined, or the version falls outside the supported range, it logs the failure and throws UnsupportedPostgresError. Immich only ships/validates pg_dump/psql binaries for majors 14–18.

Solutions

1. Run the target database on PostgreSQL 14–18 (e.g. use the tensorchord/pgvecto-rs or official image version pinned by Immich's docker-compose).
2. Check the reported version with `psql --version` / SELECT version(); and align the container image with the backup's major version.
3. Upgrade Immich to a release that supports your Postgres major, or dump/restore through an intermediate supported version.
4. Ensure the version string parses (no custom suffixes breaking semver) — verify how your Postgres distribution reports its version.

Example fix

// before
docker-compose.yml: image: postgres:19   # unsupported major
// after
docker-compose.yml: image: postgres:16   # within supported >=14 <19 range

import semver from 'semver';
// Verify Postgres version is supported before attempting a restore
const { stdout } = await exec('psql --version');
const v = stdout.match(/\d+(\.\d+)+/)?.[0];
if (!v || !semver.satisfies(v, '>=14.0.0 <19.0.0')) {
  throw new Error(`Unsupported PostgreSQL version: ${v ?? stdout}`);
}

try {
  await api.restoreDatabase(backupName);
} catch (e) {
  if (e instanceof UnsupportedPostgresError) {
    // migrate target DB to a supported major (14–18) and retry
  } else throw e;
}

When it happens

Trigger: Restoring a backup against PostgreSQL 13 or older, PostgreSQL 19+ (unreleased/preview), or when the version string cannot be parsed into a semver at all.

Common situations: Docker image bumped to a newer Postgres major than Immich supports; custom Postgres build reporting an unusual version string; old self-hosted install on PG 12/13 attempting a restore.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• Invalid backup file format!
• Invalid backup name!
• Server health check failed, no admin exists.
• Version check request failed with status

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/fbeb767d9a87eb56. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/database-backup.service.ts:214

            '--single-transaction',
            // exit with non-zero code on error
            '--set',
            'ON_ERROR_STOP=on',
          );
        }

        args.push(
          // used for progress monitoring
          '--echo-all',
          '--output=/dev/null',
        );
        break;
      }
    }

    if (!databaseMajorVersion || !databaseSemver || !satisfies(databaseSemver, '>=14.0.0 <19.0.0')) {
      this.logger.error(`Database Restore Failure: Unsupported PostgreSQL version: ${databaseVersion}`);
      throw new UnsupportedPostgresError(databaseVersion);
    }

    return {
      bin: `/usr/lib/postgresql/${databaseMajorVersion}/bin/${bin}`,
      args,
      databaseUsername,
      databasePassword,
      databaseVersion,
      databaseMajorVersion,
    };
  }

  async createDatabaseBackup(filenamePrefix: string = ''): Promise<string> {
    this.logger.debug(`Database Backup Started`);

    const { bin, args, databasePassword, databaseVersion, databaseMajorVersion } =
      await this.buildPostgresLaunchArguments('pg_dump');

View on GitHub (pinned to e55ac299a4)