chroma-core/chroma · error · Error

FTS index can only be enabled on #document key. Use createIn

Error message

FTS index can only be enabled on #document key. Use createIndex(new FtsIndexConfig(), '#document')

What it means

Full-text search indexes only the document text under '#document', so FtsIndexConfig must be created with exactly that key. Calling createIndex(new FtsIndexConfig()) without a key, or with any key other than '#document', throws — the message embeds the correct invocation.

Source

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

    }

    // 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')",
      );
    }

    // TODO: Consider removing this check in the future to allow enabling all indexes for a key
    // Disallow enabling all index types for a key (config=undefined, key="some_key")
    if (!configProvided && keyProvided && key) {
      throw new Error(
        `Cannot enable all index types for key '${key}'. Please specify a specific index configuration.`,
      );
    }

View on GitHub (pinned to aecdd12c8a)

Solutions

Use exactly: createIndex(new FtsIndexConfig(), '#document').
Import DOCUMENT_KEY from the client's schema module instead of retyping the literal string.

Example fix

// before
schema.createIndex(new FtsIndexConfig());

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

Defensive patterns

Strategy: validation

Validate before calling

function enableFts(schema: Schema): void {
  schema.createIndex(new FtsIndexConfig(), '#document');
}

Type guard

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

Try / catch

try {
  schema.createIndex(config, key);
} catch (e) {
  if (e instanceof Error && e.message.includes('FTS index can only be enabled on #document key')) {
    schema.createIndex(new FtsIndexConfig(), '#document'); // retry with the exact form
  } else {
    throw e;
  }
}

Prevention

Use one enableFts helper so the '#document' key is typed in a single place.
Do not assume the global no-key pattern used for vector indexes applies to FTS.

When it happens

Trigger: schema.createIndex(new FtsIndexConfig()); schema.createIndex(new FtsIndexConfig(), 'body'); config catalogs that omit keys for indexes assumed to be global.

Common situations: Assuming the no-key 'global' pattern used for VectorIndexConfig also works for FTS; trying to rename the document field (not possible — '#document' is fixed); hand-typing the key and mistyping it.

Related errors

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