{"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":210,"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 || !semver.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: isUrlConnection ? new URL(databaseConfig.url).password : databaseConfig.password,\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":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/immich-app/immich/blob/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/services/database-backup.service.ts#L192-L228","documentation":"Thrown as UnsupportedPostgresError(databaseVersion) by DatabaseBackupService during restore setup. The detected PostgreSQL version must satisfy semver '>=14.0.0 <19.0.0' AND both databaseMajorVersion and databaseSemver must be non-null; otherwise the dump's PG version is considered unsupported for restore. The message interpolates the detected version string.","triggerScenarios":"Restoring a database backup when the running PostgreSQL is <14 or >=19, or when the version could not be parsed (major/semver came back null/undefined).","commonSituations":"Upgrading the PG container to a v19 build before Immich supports it; a custom/old PG image (<=13) used for restore; a version-detection failure returning an empty string so coerce() yields null.","solutions":["Run a supported PostgreSQL major version (14, 15, 16, 17, or 18) for both source and target.","Re-check pg_restore / psql discovery so the version is parsed correctly (non-empty databaseVersion).","If the backup came from a now-unsupported version, dump on a supported version first, then restore."],"exampleFix":"// before\nconst cfg = await backupService.getRestoreConfig();\nawait backupService.restoreDatabaseBackup(filename);\n\n// after\nconst semver = require('semver');\nconst v = await databaseRepository.getPostgresVersion();\nconst coerced = semver.coerce(v);\nif (!coerced || !semver.satisfies(coerced, '>=14.0.0 <19.0.0')) {\n  throw new Error(`Cannot restore on PostgreSQL ${v}; use a 14–18 release.`);\n}\nawait backupService.restoreDatabaseBackup(filename);","handlingStrategy":"validation","validationCode":"const v = await databaseRepository.getPostgresVersion();\nconst c = require('semver').coerce(v);\nif (!c || !require('semver').satisfies(c, '>=14.0.0 <19.0.0')) {\n  throw new Error(`PostgreSQL ${v} is unsupported for restore; use 14–18.`);\n}","typeGuard":"function isSupportedPg(v: string | null): boolean {\n  if (!v) return false;\n  const c = require('semver').coerce(v);\n  return !!c && require('semver').satisfies(c, '>=14.0.0 <19.0.0');\n}","tryCatchPattern":null,"preventionTips":["Pin the PostgreSQL image to a supported major (14–18).","Run SELECT version(); to confirm a standard, parseable version string.","Keep source and target PG majors aligned when restoring dumps."],"tags":["database","postgres","backup","restore","version"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}