{"record":{"id":"bbfb304fd7f38117","repo":"immich-app/immich","slug":"no-vector-extension-found-available-extensions","errorCode":null,"errorMessage":"No vector extension found. Available extensions: ${VECTOR_EXTENSIONS.join(', ')}","messagePattern":"No vector extension found\\. Available extensions: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/src/repositories/database.repository.ts","lineNumber":49,"sourceCode":"import { vectorIndexQuery } from 'src/utils/database.js';\n\nexport let cachedVectorExtension: VectorExtension | undefined;\nexport async function getVectorExtension(runner: Kysely<DB>): Promise<VectorExtension> {\n  if (cachedVectorExtension) {\n    return cachedVectorExtension;\n  }\n\n  cachedVectorExtension = new ConfigRepository().getEnv().database.vectorExtension;\n  if (cachedVectorExtension) {\n    return cachedVectorExtension;\n  }\n\n  const query = `SELECT name FROM pg_available_extensions WHERE name IN (${VECTOR_EXTENSIONS.map((ext) => `'${ext}'`).join(', ')})`;\n  const { rows: availableExtensions } = await sql.raw<{ name: VectorExtension }>(query).execute(runner);\n  const extensionNames = new Set(availableExtensions.map((row) => row.name));\n  cachedVectorExtension = VECTOR_EXTENSIONS.find((ext) => extensionNames.has(ext));\n  if (!cachedVectorExtension) {\n    throw new Error(`No vector extension found. Available extensions: ${VECTOR_EXTENSIONS.join(', ')}`);\n  }\n  return cachedVectorExtension;\n}\n\nexport const probes: Record<VectorIndex, number> = {\n  [VectorIndex.Clip]: 1,\n  [VectorIndex.Face]: 1,\n};\n\n@Injectable()\nexport class DatabaseRepository {\n  private readonly asyncLock = new AsyncLock();\n\n  constructor(\n    @InjectKysely() private db: Kysely<DB>,\n    private logger: LoggingRepository,\n    private configRepository: ConfigRepository,\n  ) {","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/repositories/database.repository.ts#L31-L67","documentation":"Immich requires a Postgres vector extension to run vector searches. On startup, getVectorExtension queries pg_available_extensions for the supported candidates (pgvector, pgvecto.rs, VectorChord) and throws if none is installed or available in the Postgres instance. This is a hard startup blocker: without an extension, CLIP/smart-search embeddings cannot be stored or queried.","triggerScenarios":"First startup against a Postgres server (including the bundled one) where none of the supported vector extensions exist in pg_available_extensions, e.g. the extensions were dropped from the image or an unsupported Postgres build is used.","commonSituations":"Using a plain 'postgres' Docker image instead of the Immich-provided image with pgvector/VectorChord preinstalled; running a custom Postgres build without contrib modules; upgrading Immich to a version that dropped support for a previously used extension; pg_available_extensions missing the entry because the extension files are not on the Postgres server's filesystem.","solutions":["Use the Immich-provided Postgres container image (which ships pgvector/VectorChord) instead of a stock Postgres image","Install a supported extension on the server: CREATE EXTENSION vector; (or vectors/pg_vectorchord after installing its files) and restart Immich","Verify availability first: SELECT name FROM pg_available_extensions WHERE name IN ('vector','vectors','pg_vectorchord'); — if empty, the Postgres installation lacks the extension binaries, so install them at the OS/image level","If you intentionally switched extensions, ensure the old extension's data was migrated before removing it from the server"],"exampleFix":"// before (docker-compose.yml)\nimage: postgres:16\n// after\nimage: ghcr.io/immich-app/postgres:14-vectorchord0.3.0-pgvectors0.2.0","handlingStrategy":"validation","validationCode":"const { rows } = await sql`SELECT name FROM pg_available_extensions WHERE name IN ('vector','vectors','pg_vectorchord')`.execute(runner);\nif (rows.length === 0) throw new Error('Postgres image lacks a vector extension; use the immich postgres image');","typeGuard":"function hasVectorExtension(available: { name: string }[]): boolean {\n  return ['vector', 'vectors', 'pg_vectorchord'].some((ext) => available.some((r) => r.name === ext));\n}","tryCatchPattern":"try {\n  await repo.getVectorExtension();\n} catch (e) {\n  if ((e as Error).message.startsWith('No vector extension found')) {\n    // fall back to immich postgres image or install pgvector before proceeding\n  }\n  throw e;\n}","preventionTips":["Always use the Immich-provided Postgres image with bundled vector extensions","Smoke-test pg_available_extensions in CI before deploying","Document extension requirements for custom Postgres setups"],"tags":["database","postgres","vector-extension","startup"],"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"}