chroma-core/chroma · error · Error

Cannot create index on special key '${key}' with this config

Error message

Cannot create index on special key '${key}' with this config. Only FtsIndexConfig is allowed for #document.

What it means

'#document' is the system key holding document text, and the only index that may be created on it is a full-text search index (FtsIndexConfig). Passing any other config — VectorIndexConfig, SparseVectorIndexConfig, or any non-FTS IndexConfig — together with '#document' is rejected.

Source

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

      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(
        "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(

View on GitHub (pinned to aecdd12c8a)

Solutions

Use the exact supported form: createIndex(new FtsIndexConfig(), '#document').
If you wanted a vector or sparse vector index, target the global config or a user key instead — never '#document'.

Example fix

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

// after
schema.createIndex(new FtsIndexConfig(), '#document');

Defensive patterns

Strategy: validation

Validate before calling

function createDocumentIndex(schema: Schema, config: IndexConfig): void {
  if (config instanceof FtsIndexConfig) {
    schema.createIndex(config, '#document');
    return;
  }
  throw new Error('Only FtsIndexConfig may be created on #document');
}

Type guard

const isFtsForDocument = (config: IndexConfig, key?: string): boolean =>
  config instanceof FtsIndexConfig && (key === undefined || key === '#document');

Try / catch

try {
  schema.createIndex(config, key);
} catch (e) {
  if (e instanceof Error && e.message.includes('Only FtsIndexConfig is allowed for #document')) {
    // switch to createIndex(new FtsIndexConfig(), '#document') or target a user key
  } else {
    throw e;
  }
}

Prevention

Special-case '#document' in index catalogs: FTS is the only legal config there.
Do not apply one config uniformly across all keys including system keys.

When it happens

Trigger: schema.createIndex(new VectorIndexConfig(), '#document'); schema.createIndex(new SparseVectorIndexConfig(), '#document'); generic loops that pair every config in a catalog with every key including '#document'.

Common situations: Trying to index document text with something other than FTS; uniform 'apply this config to all fields' code; misunderstanding that '#document' exists solely for full-text search.

Related errors

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