chroma-core/chroma · error · Error

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

Error message

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

What it means

The delete-side twin of the '#document' creation rule: on '#document' the only index that exists — and can be deleted — is full-text search, so deleteIndex targeting '#document' must pass an FtsIndexConfig. Any other config (including undefined) paired with '#document' throws, because undefined fails the instanceof FtsIndexConfig check.

Source

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

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

    // Disallow using special internal key #embedding
    if (keyProvided && key && key === EMBEDDING_KEY) {
      throw new Error("Cannot modify #embedding. Currently not supported");
    }

    // Only allow #document with FtsIndexConfig (to disable FTS)
    if (
      keyProvided &&
      key === DOCUMENT_KEY &&
      !(config instanceof FtsIndexConfig)
    ) {
      throw new Error(
        `Cannot delete index on special key '${key}' with this config. Only FtsIndexConfig is allowed for #document.`,
      );
    }

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

    // TODO: Consider removing these checks in the future to allow disabling vector and sparse vector indexes
    // Temporarily disallow deleting vector index (both globally and per-key)
    if (config instanceof VectorIndexConfig) {
      throw new Error("Deleting vector index is not currently supported.");
    }

    // Temporarily disallow deleting sparse vector index (both globally and per-key)

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Use deleteIndex(new FtsIndexConfig(), '#document') to disable full-text search.
  2. Always pass the config explicitly for '#document' — key-only deletion is not accepted there.

Example fix

// before
schema.deleteIndex(undefined, '#document');

// after
schema.deleteIndex(new FtsIndexConfig(), '#document');
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
  schema.deleteIndex(config, '#document');
} catch (e) {
  if (e instanceof Error && e.message.includes('Only FtsIndexConfig is allowed for #document')) {
    schema.deleteIndex(new FtsIndexConfig(), '#document'); // retry with FTS config
  } else {
    throw e;
  }
}

Prevention

When it happens

Trigger: schema.deleteIndex(new VectorIndexConfig(), '#document'); schema.deleteIndex(undefined, '#document'); schema.deleteIndex(new SparseVectorIndexConfig(), '#document').

Common situations: Trying to delete 'the document index' generically without naming FTS; reusing createIndex argument patterns for deletion; assuming key-only deletion works for system keys.

Related errors

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