{"record":{"id":"fbeb767d9a87eb56","repo":"immich-app/immich","slug":"unsupported-postgresql-version-databaseversion","errorCode":null,"errorMessage":"Unsupported PostgreSQL version: ${databaseVersion}","messagePattern":"Unsupported PostgreSQL version: (.+?)","errorType":"exception","errorClass":"UnsupportedPostgresError","httpStatus":null,"severity":"critical","filePath":"server/src/services/database-backup.service.ts","lineNumber":214,"sourceCode":"            '--single-transaction',\n            // exit with non-zero code on error\n            '--set',\n            'ON_ERROR_STOP=on',\n          );\n        }\n\n        args.push(\n          // used for progress monitoring\n          '--echo-all',\n          '--output=/dev/null',\n        );\n        break;\n      }\n    }\n\n    if (!databaseMajorVersion || !databaseSemver || !satisfies(databaseSemver, '>=14.0.0 <19.0.0')) {\n      this.logger.error(`Database Restore Failure: Unsupported PostgreSQL version: ${databaseVersion}`);\n      throw new UnsupportedPostgresError(databaseVersion);\n    }\n\n    return {\n      bin: `/usr/lib/postgresql/${databaseMajorVersion}/bin/${bin}`,\n      args,\n      databaseUsername,\n      databasePassword,\n      databaseVersion,\n      databaseMajorVersion,\n    };\n  }\n\n  async createDatabaseBackup(filenamePrefix: string = ''): Promise<string> {\n    this.logger.debug(`Database Backup Started`);\n\n    const { bin, args, databasePassword, databaseVersion, databaseMajorVersion } =\n      await this.buildPostgresLaunchArguments('pg_dump');\n","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/database-backup.service.ts#L196-L232","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Check the reported version with `psql --version` / SELECT version(); and align the container image with the backup's major version.","Upgrade Immich to a release that supports your Postgres major, or dump/restore through an intermediate supported version.","Ensure the version string parses (no custom suffixes breaking semver) — verify how your Postgres distribution reports its version."],"exampleFix":"// before\ndocker-compose.yml: image: postgres:19   # unsupported major\n// after\ndocker-compose.yml: image: postgres:16   # within supported >=14 <19 range","handlingStrategy":"validation","validationCode":"import semver from 'semver';\n// Verify Postgres version is supported before attempting a restore\nconst { stdout } = await exec('psql --version');\nconst v = stdout.match(/\\d+(\\.\\d+)+/)?.[0];\nif (!v || !semver.satisfies(v, '>=14.0.0 <19.0.0')) {\n  throw new Error(`Unsupported PostgreSQL version: ${v ?? stdout}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await api.restoreDatabase(backupName);\n} catch (e) {\n  if (e instanceof UnsupportedPostgresError) {\n    // migrate target DB to a supported major (14–18) and retry\n  } else throw e;\n}","preventionTips":["Pin the Postgres image major version to one Immich supports (14–18).","Check SELECT version(); after any database upgrade before running restores.","Read Immich release notes for newly supported Postgres majors before upgrading."],"tags":["postgresql","database-restore","version-check","backup"],"backgroundTag":"unsupported-platform","analyzedSha":"e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c","analyzedAt":"2026-09-15T07:20:19.675Z","contentChangedAt":"2026-09-15T07:20:19.675Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}