{"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":"Error","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 && semver.eq(version, '0.0.0'))) {\n        throw new Error(messages.nightlyVersion({ name, extension, version: '0.0.0' }));\n      }\n\n      if (!semver.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 && semver.gt(availableVersion, installedVersion)) {\n        await this.updateExtension(extension, availableVersion);\n      } else if (installedVersion && !semver.satisfies(installedVersion, extensionRange)) {\n        throw new Error(messages.outOfRange({ name, extension, version: installedVersion, range: extensionRange }));\n      } else if (installedVersion && semver.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/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/services/database.service.ts#L65-L101","documentation":"The vector extension that Postgres makes available (default_version in pg_available_extensions) does not satisfy the semver range Immich requires for that extension. This guard runs before any CREATE EXTENSION, so it fails even when nothing is installed yet. It prevents Immich from activating an extension version known to be incompatible with its schema and operators.","triggerScenarios":"On bootstrap, availableVersion is set and non-zero but !semver.satisfies(availableVersion, extensionRange). Example: pgvector 0.4.x available while Immich requires >=0.5.0, or a too-new pgvecto.rs that broke compatibility.","commonSituations":"Postgres image bundled with an older pgvector; pinned an extension version that has since fallen out of the supported range after an Immich upgrade; using a Linux distro package that ships an old pgvector.","solutions":["Check Immich's required range via getExtensionVersionRange for your extension (see the supported versions table in docs) and install a version inside it.","Update the extension package in the Postgres container/image to a compatible release (e.g. upgrade pgvector to a supported tag).","If only a too-new version is available, downgrade the package to the highest version still inside extensionRange.","Restart Postgres then Immich so bootstrap re-runs the satisfies() check."],"exampleFix":"# check available + required\n-- SELECT name, default_version FROM pg_available_extensions WHERE name='vector';\n# install a compatible pgvector release matching Immich's range\nRUN apt-get install -y postgresql-16-pgvector=0.7.*","handlingStrategy":"validation","validationCode":"import pg from 'pg';\nimport semver from 'semver';\nconst REQUIRED = '>=0.5.0'; // replace with Immich's getExtensionVersionRange for your version\nconst client = new pg.Client({ connectionString: process.env.DB_URL });\nawait client.connect();\nconst { rows } = await client.query(\n  \"SELECT name, default_version FROM pg_available_extensions WHERE name IN ('vector','vectors');\"\n);\nfor (const r of rows) {\n  if (r.default_version && !semver.satisfies(semver.coerce(r.default_version)!, REQUIRED)) {\n    throw new Error(`${r.name} ${r.default_version} does not satisfy ${REQUIRED}`);\n  }\n}","typeGuard":"import semver from 'semver';\nconst extensionInRange = (version: string | undefined, range: string) =>\n  !!version && !!semver.coerce(version) && semver.satisfies(semver.coerce(version)!, range);","tryCatchPattern":"try {\n  await app.start();\n} catch (e) {\n  if (/only supports/.test(String(e?.message))) {\n    logger.fatal('Vector extension out of supported range - install a compatible version');\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Track Immich's documented supported extension versions per server release.","Update the extension package whenever you upgrade Immich.","Add a CI check that asserts the deployed image's extension satisfies the range."],"tags":["postgres","database","extension","version","semver","pgvector","bootstrap","immich","config"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}