{"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":"Error","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 = semver.coerce(version);\n    const postgresRange = this.databaseRepository.getPostgresVersionRange();\n    if (!current || !semver.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 && 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 }));","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/immich-app/immich/blob/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/services/database.service.ts#L57-L93","documentation":"Immich requires a vector similarity search extension (pgvector 'vector' or pgvecto.rs 'vectors', a.k.a. Chord) to be present in the Postgres instance before it can start. On bootstrap the DatabaseService queries pg_extension/pg_available_extensions for VECTOR_EXTENSIONS; if the configured extension has no availableVersion, startup aborts with this message. It is a hard precondition for running the server because vector indexes back CLIP and face recognition search.","triggerScenarios":"AppBootstrap event fires, DatabaseService.onBootstrap runs, getVectorExtension returns the configured extension (e.g. 'vectors'), getExtensionVersions returns no row with a non-null availableVersion for it. Triggered: fresh DB without the extension, a custom/minimal Postgres image, or VECTOR_EXTENSIONS env var pointing at an extension the image lacks.","commonSituations":"Using a plain postgres Docker image instead of the pgvector/pgvecto.rs image; mis-setting the vector extension env var; Postgres upgrade that dropped the extension; RDS/Cloud SQL without the vector extension package installed.","solutions":["Switch to the Immich-bundled or pgvector/pgvecto.rs Postgres image (tensorchord/pgvecto.rs or pgvector/pgvector) matching the version in docker/docker-compose.yml.","Inside the running Postgres container run 'SELECT name, default_version FROM pg_available_extensions WHERE name IN ('vector','vectors');' to confirm the extension package exists; if absent, install the package for that PG major version.","Verify the IMMICH/DB vector extension env var matches an extension that is actually packaged (default is 'vectors' for the bundled image); change it to 'vector' only if you installed pgvector.","Restart the Immich server after the Postgres image/extension is fixed so the bootstrap check re-runs."],"exampleFix":"# before: plain postgres image\n#  image: postgres:16\n# after: image with the vector extension\nimage: tensorchord/pgvectors:pg16\n# then in psql confirm:\n-- SELECT * FROM pg_available_extensions WHERE name = 'vectors';","handlingStrategy":"validation","validationCode":"// before starting Immich, verify the extension package is present in Postgres\nimport pg from 'pg';\nconst client = new pg.Client({ connectionString: process.env.DB_URL });\nawait client.connect();\nconst res = await client.query(\n  \"SELECT name FROM pg_available_extensions WHERE name IN ('vector','vectors');\"\n);\nif (res.rowCount === 0) {\n  throw new Error('No vector extension available in Postgres - install pgvector/pgvecto.rs first');\n}","typeGuard":"const hasVectorExtension = (rows: { name: string }[]) =>\n  rows.some((r) => r.name === 'vector' || r.name === 'vectors');","tryCatchPattern":"try {\n  await app.start(); // triggers DatabaseService.onBootstrap\n} catch (e) {\n  if (/extension is not available/.test(String(e?.message))) {\n    logger.fatal('Vector extension missing - fix the Postgres image before retrying');\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Use the Immich-provided docker-compose Postgres image or a known pgvector/pgvecto.rs image.","Add a startup healthcheck that queries pg_available_extensions for the vector extension.","Pin extension image tags - do not rely on 'latest'.","Document the required vector extension in deployment runbooks."],"tags":["postgres","database","bootstrap","pgvector","extension","immich","config"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}