{"record":{"id":"7af374b85b34c1ee","repo":"immich-app/immich","slug":"the-name-extension-version-is-version-but-i","errorCode":null,"errorMessage":"The ${name} extension version is ${version}, but Immich only supports ${range}.\n    Please change ${name} to a compatible version in the Postgres instance.","messagePattern":"The (.+?) extension version is (.+?), but Immich only supports (.+?)\\.\n    Please change (.+?) to a compatible version in the Postgres instance\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/src/services/database.service.ts","lineNumber":83,"sourceCode":"    }\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      }\n\n      if (!satisfies(availableVersion, extensionRange)) {\n        throw new Error(messages.outOfRange({ name, extension, version: availableVersion, range: extensionRange }));\n      }\n\n      if (!installedVersion) {\n        await this.createExtension(extension);\n      }\n\n      if (installedVersion && gt(availableVersion, installedVersion)) {\n        await this.updateExtension(extension, availableVersion);\n      } else if (installedVersion && !satisfies(installedVersion, extensionRange)) {\n        throw new Error(messages.outOfRange({ name, extension, version: installedVersion, range: extensionRange }));\n      } else if (installedVersion && lt(availableVersion, installedVersion)) {\n        throw new Error(messages.invalidDowngrade({ name, extension, availableVersion, installedVersion }));\n      }\n\n      try {\n        await this.databaseRepository.reindexVectorsIfNeeded([VectorIndex.Clip, VectorIndex.Face]);\n      } catch (error) {\n        this.logger.warn(","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/database.service.ts#L65-L101","documentation":"The extension's available version must satisfy the range required by this Immich release (getExtensionVersionRange, e.g. ^0.3.0 for VectorChord or >=0.5.5 <1 for pgvector). If the newest version available in the Postgres instance is outside that range, startup aborts with messages.outOfRange.","triggerScenarios":"Bootstrap where getAvailableExtension returns a version like 0.2.x or 0.4.x when Immich requires a different major/minor range — e.g. pgvector too old in a stock image, or VectorChord too new for the pinned Immich release.","commonSituations":"Upgrading the extension image ahead of Immich; running an old Postgres image after upgrading Immich; Debian packages shipping older pgvector.","solutions":["Upgrade (or downgrade) the extension to a version within the required range shown in the error, e.g. pull a matching ghcr.io/immich-app/postgres image tag.","Upgrade Immich to a version whose extension range matches what your Postgres image provides.","Verify with 'SELECT * FROM pg_available_extension_versions' that the required version is actually installable in the instance."],"exampleFix":"# before\nimage: tensorchord/pgvecto-rs:pg15-v0.2.0\n# after\nimage: ghcr.io/immich-app/postgres:15-vectorchord0.3.0","handlingStrategy":"try-catch","validationCode":"const { rows } = await db.query(\"SELECT max(version) FROM pg_available_extension_versions WHERE name='vectorchord'\");\nif (!semver.satisfies(rows[0].max, '^0.3.0')) console.error('Extension version out of supported range');","typeGuard":null,"tryCatchPattern":"try {\n  await server.start();\n} catch (e) {\n  if (/only supports/.test(e.message)) {\n    console.error('Align extension version with the range Immich requires:', e.message);\n  } else throw e;\n}","preventionTips":["Upgrade Immich and its extension images together.","Read the release notes for the required extension range before updating either side.","Pin image tags in docker-compose instead of using :latest."],"tags":["postgres","extension","version","compatibility","bootstrap"],"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"}