chroma-core/chroma · error · Error

Sparse vector index must be created on a specific key. Pleas

Error message

Sparse vector index must be created on a specific key. Please specify a key using: createIndex(new SparseVectorIndexConfig(...), 'your_key')

What it means

Sparse vector indexes are per-key — each one targets a specific sparse embedding field — so SparseVectorIndexConfig cannot be applied globally. createIndex(new SparseVectorIndexConfig(...)) with no key throws; the message shows the required call shape including the key argument.

Source

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

        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.`,
      );
    }

    if (configProvided && !keyProvided) {
      this.setIndexInDefaults(config as IndexConfig, true);
    } else if (configProvided && keyProvided && key) {
      this.setIndexForKey(key, config as IndexConfig, true);
    }

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass the target field: createIndex(new SparseVectorIndexConfig(...), 'your_sparse_key').
Make the key a required parameter in your own wrapper around sparse index creation.

Example fix

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

// after
schema.createIndex(new SparseVectorIndexConfig(), 'sparse_embedding');

Defensive patterns

Strategy: validation

Validate before calling

function createSparseIndex(schema: Schema, config: SparseVectorIndexConfig, key: string): void {
  if (!key) throw new Error('Sparse vector index requires an explicit key');
  schema.createIndex(config, key);
}

Type guard

const isKeyedIndexConfig = (config: IndexConfig): boolean =>
  config instanceof SparseVectorIndexConfig;

Try / catch

try {
  schema.createIndex(config);
} catch (e) {
  if (e instanceof Error && e.message.includes('Sparse vector index must be created on a specific key')) {
    schema.createIndex(config, 'sparse_embedding'); // retry with the target key
  } else {
    throw e;
  }
}

Prevention

Model sparse index creation in your own wrapper with a required key parameter.
Keep per-key vs global requirements in a small config-type table your team references.

When it happens

Trigger: schema.createIndex(new SparseVectorIndexConfig()); copying the global VectorIndexConfig pattern for sparse indexes; a config-driven loop where the key variable defaults to undefined for sparse entries.

Common situations: Hybrid search (dense + sparse) setups adding sparse indexes; uniformly applying an index catalog where some entries lack target keys.

Related errors

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