{"record":{"id":"a90ae82752fca9bb","repo":"immich-app/immich","slug":"unsupported-vector-extension-vectorextension","errorCode":null,"errorMessage":"Unsupported vector extension: '${vectorExtension}'","messagePattern":"Unsupported vector extension: '(.+?)'","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"server/src/utils/database.ts","lineNumber":1122,"sourceCode":"    case DatabaseExtension.VectorChord: {\n      return `\n        CREATE INDEX IF NOT EXISTS ${indexName} ON ${table} USING vchordrq (embedding vector_cosine_ops) WITH (options = $$\n        residual_quantization = false\n        [build.internal]\n        lists = [${lists ?? 1}]\n        spherical_centroids = true\n        build_threads = 4\n        sampling_factor = 1024\n        $$)`;\n    }\n    case DatabaseExtension.Vector: {\n      return `\n        CREATE INDEX IF NOT EXISTS ${indexName} ON ${table}\n        USING hnsw (embedding vector_cosine_ops)\n        WITH (ef_construction = 300, m = 16)`;\n    }\n    default: {\n      throw new Error(`Unsupported vector extension: '${vectorExtension}'`);\n    }\n  }\n}\n\nexport const updateLockedColumns = <T extends Record<string, unknown> & { lockedProperties?: LockableProperty[] }>(\n  exif: T,\n) => {\n  exif.lockedProperties = lockableProperties.filter((property) => Object.hasOwn(exif, property));\n  return exif;\n};\n","sourceCodeStart":1104,"sourceCodeEnd":1133,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/utils/database.ts#L1104-L1133","documentation":"The vector index DDL builder only knows specific Postgres vector extensions (e.g. vectors from pgvecto.rs and vector from pgvector, for hnsw indexes). An unknown vectorExtension reaches the switch's default branch and throws, because the correct CREATE INDEX syntax differs per extension.","triggerScenarios":"Database migration/setup with a vectorExt setting that is not one of the supported extensions, e.g. after renaming the extension between Immich versions or a hand-modified environment.","commonSituations":"Upgrading Immich across the pgvecto.rs -> pgvector migration with leftover config; setting an invalid IMMICH_VECTOR extension env value; custom Docker images with an unexpected extension installed.","solutions":["Set the vector extension to a supported value (pgvector's 'vector' or 'vectors' as per your Immich version)","Follow the official pgvecto.rs -> pgvector migration guide if upgrading from old versions","Verify the extension is actually installed in the DB: SELECT * FROM pg_extension","Rebuild the Immich server container to reset the computed extension value"],"exampleFix":"// before\nVECTOR_EXTENSION=pgvectors\n// after\nVECTOR_EXTENSION=vector","handlingStrategy":"validation","validationCode":"const SUPPORTED = ['vector', 'vectors'];\nif (!SUPPORTED.includes(vectorExtension)) {\n  throw new Error(`Set VECTOR_EXTENSION to one of: ${SUPPORTED.join(', ')}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runMigrations();\n} catch (e) {\n  if (/Unsupported vector extension/.test(e.message)) {\n    // correct the extension env value and follow the official extension migration guide\n  }\n}","preventionTips":["Never hardcode the extension name; read it from the provided config surface","Follow release notes when Immich migrates between pgvecto.rs and pgvector","Verify the installed extension with pg_extension before starting Immich"],"tags":["database","postgres","vector","migration"],"backgroundTag":"invalid-config-value","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"}