chroma-core/chroma · error · Error

Cannot create index on special key '${key}'. This key is man

Error message

Cannot create index on special key '${key}'. This key is managed automatically by the system. Invoke createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.

What it means

'#embedding' is the system-managed schema key that stores the collection's vectors; the Schema class seeds and configures it automatically. createIndex therefore refuses any call that explicitly targets '#embedding' — the vector index is configured globally via createIndex(new VectorIndexConfig(...)) without a key, as the error message itself instructs.

Source

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

   */
  setCmek(cmek: Cmek | null): this {
    this.cmek = cmek;
    return this;
  }

  createIndex(config?: IndexConfig, key?: string): this {
    const configProvided = config !== undefined && config !== null;
    const keyProvided = key !== undefined && key !== null;

    if (!configProvided && !keyProvided) {
      throw new Error(
        "Cannot enable all index types globally. Must specify either config or key.",
      );
    }

    // Disallow using special internal key #embedding
    if (keyProvided && key && key === EMBEDDING_KEY) {
      throw new Error(
        `Cannot create index on special key '${key}'. This key is managed automatically by the system. Invoke createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.`,
      );
    }

    // Only allow #document with FtsIndexConfig
    if (
      keyProvided &&
      key === DOCUMENT_KEY &&
      !(config instanceof FtsIndexConfig)
    ) {
      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(

View on GitHub (pinned to aecdd12c8a)

Solutions

Configure the vector index globally: call createIndex(new VectorIndexConfig(...)) with NO key argument.
Skip system keys (anything starting with '#') when creating indexes programmatically.

Example fix

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

// after
schema.createIndex(new VectorIndexConfig()); // global, no key

Defensive patterns

Strategy: validation

Validate before calling

const SYSTEM_KEYS = new Set(['#embedding', '#document']);
for (const [key, cfg] of indexPlan) {
  if (SYSTEM_KEYS.has(key)) continue;
  schema.createIndex(cfg, key);
}

Type guard

const isSystemKey = (key: string): boolean =>
  key === '#embedding' || key === '#document';

Try / catch

try {
  schema.createIndex(cfg, key);
} catch (e) {
  if (e instanceof Error && e.message.includes('#embedding')) {
    // skip system keys when applying a config catalog
  } else {
    throw e;
  }
}

Prevention

Filter system keys before programmatic index creation.
Remember the layout: vector index is global (no key), FTS belongs to '#document', everything else uses user keys.

When it happens

Trigger: schema.createIndex(new VectorIndexConfig(), '#embedding'); createIndex(cfg, '#embedding') with any config; a loop over schema.keys that includes system keys and calls createIndex for each entry.

Common situations: Programmatically creating indexes by iterating Schema keys and forgetting to exclude system keys; assuming per-field vector indexes exist (there is one vector index per collection).

Related errors

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