chroma-core/chroma · error · Error

Vector index cannot be enabled on specific keys. Use createI

Error message

Vector index cannot be enabled on specific keys. Use createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.

What it means

A collection has exactly one vector index, stored under the system '#embedding' key, so VectorIndexConfig can only be applied collection-wide. Passing any key together with a VectorIndexConfig throws this error; the global form is createIndex(new VectorIndexConfig(...)) with no key argument.

Source

Thrown at clients/new-js/packages/chromadb/src/schema.ts:546

      throw new Error(
        `Cannot create index on special key '${key}' with this config. Only FtsIndexConfig is allowed for #document.`,
      );
    }

    // Disallow any key starting with # (except #document which allows FTS)
    if (keyProvided && key && key.startsWith("#") && key !== DOCUMENT_KEY) {
      throw new Error(
        "key cannot begin with '#'. Keys starting with '#' are reserved for system use.",
      );
    }

    // Special handling for vector index
    if (config instanceof VectorIndexConfig) {
      if (!keyProvided) {
        this.setVectorIndexConfig(config);
        return this;
      }
      throw new Error(
        "Vector index cannot be enabled on specific keys. Use createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.",
      );
    }

    // FTS index is only allowed on #document key
    if (
      config instanceof FtsIndexConfig &&
      (!keyProvided || key !== DOCUMENT_KEY)
    ) {
      throw new Error(
        "FTS index can only be enabled on #document key. Use createIndex(new FtsIndexConfig(), '#document')",
      );
    }

    if (config instanceof SparseVectorIndexConfig && !keyProvided) {
      throw new Error(
        "Sparse vector index must be created on a specific key. Please specify a key using: createIndex(new SparseVectorIndexConfig(...), 'your_key')",
      );

View on GitHub (pinned to aecdd12c8a)

Solutions

Call createIndex(new VectorIndexConfig(...)) WITHOUT the key argument.
For multiple embedding fields, use separate collections (or per-key sparse vector indexes where appropriate).

Example fix

// before
schema.createIndex(new VectorIndexConfig(), 'my_vector');

// after
schema.createIndex(new VectorIndexConfig()); // applies globally

Defensive patterns

Strategy: validation

Validate before calling

function applyIndex(schema: Schema, config: IndexConfig, key?: string): void {
  if (config instanceof VectorIndexConfig) {
    schema.createIndex(config); // global only, ignore any key
    return;
  }
  schema.createIndex(config, key);
}

Type guard

const isGlobalOnlyConfig = (config: IndexConfig): boolean =>
  config instanceof VectorIndexConfig;

Try / catch

try {
  schema.createIndex(config, key);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Vector index cannot be enabled on specific keys')) {
    schema.createIndex(config); // retry globally
  } else {
    throw e;
  }
}

Prevention

Branch on config type before calling createIndex: VectorIndexConfig goes global, always.
For multiple embedding fields, plan separate collections up front.

When it happens

Trigger: schema.createIndex(new VectorIndexConfig(...), 'embeddings'); loops applying one config to many keys; porting a multi-embedding-field design from a database that supports per-column vector indexes.

Common situations: Migrating from pgvector-style schemas with several indexed vector columns; uniformly applying a catalog of configs to all keys; assuming per-field HNSW indexes exist.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/41bcaff9cea5e836. Report an issue: GitHub.