{"record":{"id":"9ab56d0829ae995c","repo":"immich-app/immich","slug":"the-name-extension-is-not-available-in-this-pos","errorCode":null,"errorMessage":"The ${name} extension is not available in this Postgres instance.\n    If using a container image, ensure the image has the extension installed.","messagePattern":"The (.+?) extension is not available in this Postgres instance\\.\n    If using a container image, ensure the image has the extension installed\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/src/services/database.service.ts","lineNumber":75,"sourceCode":"  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      }\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 }));","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/database.service.ts#L57-L93","documentation":"During bootstrap, each required vector extension (vectorchord/pgsql-vectorchord or pgvector per EXTENSION_NAMES) is checked via getExtensionVersions. If pg_available_extensions reports no available version, the extension is not installed in the Postgres image, so Immich aborts startup with messages.notInstalled(name).","triggerScenarios":"Starting Immich against a vanilla postgres image (e.g. postgres:15) that lacks the required vector extension, so no availableVersion exists for the configured extension.","commonSituations":"Swapping from tensorchord/pgvecto-rs image to stock postgres; missing image update after Immich release changed the required extension; extension name typo in DB environment config.","solutions":["Use the official Immich Postgres image (ghcr.io/immich-app/postgres or tensorchord pgvecto-rs image) that bundles the extension.","Install the required extension package into your Postgres instance and ensure CREATE EXTENSION can find it (shared_preload_libraries for pgvecto.rs).","Check DB_VECTOR_EXTENSION config points at an extension actually present in the image."],"exampleFix":"// before\nimage: postgres:15\n// after\nimage: ghcr.io/immich-app/postgres:15-vectorchord0.3.0","handlingStrategy":"validation","validationCode":"const { rows } = await db.query(\"SELECT name FROM pg_available_extensions WHERE name IN ('vectorchord','vectors','pgvector')\");\nif (!rows.length) console.error('Postgres image lacks the required vector extension');","typeGuard":null,"tryCatchPattern":"try {\n  await server.start();\n} catch (e) {\n  if (/extension is not available/.test(e.message)) {\n    console.error('Switch to the official Immich Postgres image that bundles', e.message);\n  } else throw e;\n}","preventionTips":["Use ghcr.io/immich-app/postgres / tensorchord images that ship the extension.","Keep DB extension env vars in sync with the image actually used.","Verify pg_available_extensions after any Postgres image change."],"tags":["postgres","extension","bootstrap","vector"],"backgroundTag":"missing-dependency","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"}