immich-app/immich · critical · Error

Unsupported vector extension

Error message

Unsupported vector extension: '${vectorExtension}'

What it means

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.

Solutions

1. Set the vector extension to a supported value (pgvector's 'vector' or 'vectors' as per your Immich version)
2. Follow the official pgvecto.rs -> pgvector migration guide if upgrading from old versions
3. Verify the extension is actually installed in the DB: SELECT * FROM pg_extension
4. Rebuild the Immich server container to reset the computed extension value

Example fix

// before
VECTOR_EXTENSION=pgvectors
// after
VECTOR_EXTENSION=vector

const SUPPORTED = ['vector', 'vectors'];
if (!SUPPORTED.includes(vectorExtension)) {
  throw new Error(`Set VECTOR_EXTENSION to one of: ${SUPPORTED.join(', ')}`);
}

try {
  await runMigrations();
} catch (e) {
  if (/Unsupported vector extension/.test(e.message)) {
    // correct the extension env value and follow the official extension migration guide
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• extension is not installed
• Migration " " failed
• Table does not exist, skipping reindexing. This is only…
• Column 'embedding' does not exist in table
• Could not retrieve dimension size of column

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/a90ae82752fca9bb. Report an issue: GitHub.

Appendix: source

Thrown at server/src/utils/database.ts:1122

    case DatabaseExtension.VectorChord: {
      return `
        CREATE INDEX IF NOT EXISTS ${indexName} ON ${table} USING vchordrq (embedding vector_cosine_ops) WITH (options = $$
        residual_quantization = false
        [build.internal]
        lists = [${lists ?? 1}]
        spherical_centroids = true
        build_threads = 4
        sampling_factor = 1024
        $$)`;
    }
    case DatabaseExtension.Vector: {
      return `
        CREATE INDEX IF NOT EXISTS ${indexName} ON ${table}
        USING hnsw (embedding vector_cosine_ops)
        WITH (ef_construction = 300, m = 16)`;
    }
    default: {
      throw new Error(`Unsupported vector extension: '${vectorExtension}'`);
    }
  }
}

export const updateLockedColumns = <T extends Record<string, unknown> & { lockedProperties?: LockableProperty[] }>(
  exif: T,
) => {
  exif.lockedProperties = lockableProperties.filter((property) => Object.hasOwn(exif, property));
  return exif;
};

View on GitHub (pinned to e55ac299a4)