{"record":{"id":"bae9692cdc0f32f8","repo":"immich-app/immich","slug":"invalid-postgresql-version-found-version-but","errorCode":null,"errorMessage":"Invalid PostgreSQL version. Found ${version}, but needed ${postgresRange}. Please use a supported version.","messagePattern":"Invalid PostgreSQL version\\. Found (.+?), but needed (.+?)\\. Please use a supported version\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/src/services/database.service.ts","lineNumber":62,"sourceCode":"    This may be because Immich does not have the necessary permissions to drop the extension.\n\n    Please run 'DROP EXTENSION ${extension};' manually as a superuser.\n    See https://docs.immich.app/guides/database-queries for how to query the database.`,\n  invalidDowngrade: ({ name, installedVersion, availableVersion }: InvalidDowngradeArgs) =>\n    `The database currently has ${name} ${installedVersion} activated, but the Postgres instance only has ${availableVersion} available.\n    This most likely means the extension was downgraded.\n    If ${name} ${installedVersion} is compatible with Immich, please ensure the Postgres instance has this available.`,\n};\n\n@Injectable()\nexport class DatabaseService extends BaseService {\n  @OnEvent({ name: 'AppBootstrap', priority: BootstrapEventPriority.DatabaseService })\n  async onBootstrap() {\n    const version = await this.databaseRepository.getPostgresVersion();\n    const current = coerce(version);\n    const postgresRange = this.databaseRepository.getPostgresVersionRange();\n    if (!current || !satisfies(current, postgresRange)) {\n      throw new Error(\n        `Invalid PostgreSQL version. Found ${version}, but needed ${postgresRange}. Please use a supported version.`,\n      );\n    }\n\n    await this.databaseRepository.withLock(DatabaseLock.Migrations, async () => {\n      const extension = await this.databaseRepository.getVectorExtension();\n      const name = EXTENSION_NAMES[extension];\n      const extensionRange = this.databaseRepository.getExtensionVersionRange(extension);\n\n      const extensionVersions = await this.databaseRepository.getExtensionVersions(VECTOR_EXTENSIONS);\n      const { installedVersion, availableVersion } = extensionVersions.find((v) => v.name === extension) ?? {};\n      if (!availableVersion) {\n        throw new Error(messages.notInstalled(name));\n      }\n\n      if ([availableVersion, installedVersion].some((version) => version && eq(version, '0.0.0'))) {\n        throw new Error(messages.nightlyVersion({ name, extension, version: '0.0.0' }));\n      }","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/database.service.ts#L44-L80","documentation":"On app bootstrap, DatabaseService reads the server's PostgreSQL version, coerces it, and checks it against the supported semver range (getPostgresVersionRange, e.g. ^14.0.0). If the version cannot be coerced or is outside the supported range, bootstrap fails hard so Immich never runs against an unsupported database.","triggerScenarios":"Starting the Immich server while connected to PostgreSQL 12/13/17+ (or any version outside the supported range), or when getPostgresVersion returns an unparseable value.","commonSituations":"Docker image with unsupported PG version; user upgraded the Postgres container past the supported range; self-hosted install pointing at an old system Postgres.","solutions":["Upgrade or downgrade the PostgreSQL server to a version inside the supported range (see getPostgresVersionRange, e.g. 14–15 for older Immich releases).","Update Immich to a release that supports your Postgres version.","Ensure the server actually connects to the intended Postgres instance (check DB_HOST/DB_PORT); a proxy returning a bogus version string also triggers this."],"exampleFix":"// docker-compose.yml before\nimage: postgres:13\n// after\nimage: postgres:15","handlingStrategy":"try-catch","validationCode":"const { rows } = await db.query('SHOW server_version');\nconst major = parseInt(rows[0].server_version);\nif (major < 14 || major > 15) console.warn('Unsupported Postgres version for this Immich release');","typeGuard":null,"tryCatchPattern":"try {\n  await server.start();\n} catch (e) {\n  if (/Invalid PostgreSQL version/.test(e.message)) {\n    console.error('Switch the Postgres container to a supported version:', e.message);\n  } else throw e;\n}","preventionTips":["Pin docker-compose to the Postgres image tag documented for your Immich release.","Check Immich release notes before upgrading Postgres.","Confirm DB_HOST/DB_PORT point at the intended instance."],"tags":["postgres","version","bootstrap","compatibility"],"backgroundTag":"value-out-of-range","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"}