chroma-core/chroma · error · Error

Cannot enable all index types globally. Must specify either

Error message

Cannot enable all index types globally. Must specify either config or key.

What it means

Schema.createIndex(config?, key?) requires at least one argument: a concrete IndexConfig to enable, optionally scoped to a key. Calling it with neither would mean 'turn on every index type globally', which the API deliberately rejects — you must state which index you want.

Source

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

   * @example
   * ```typescript
   * const schema = new Schema();
   * schema.setCmek(Cmek.gcp(
   *   "projects/my-project/locations/us-central1/keyRings/my-ring/cryptoKeys/my-key"
   * ));
   * ```
   */
  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(

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass a global config: createIndex(new VectorIndexConfig(...)) configures the collection-wide vector index.
Or pass config plus key for a scoped index, e.g. createIndex(new FtsIndexConfig(), '#document').
If the index is optional, guard the call: if (cfg) schema.createIndex(cfg).

Example fix

// before
schema.createIndex(); // nothing specified

// after
schema.createIndex(new VectorIndexConfig()); // global vector index config

Defensive patterns

Strategy: validation

Validate before calling

function createIndexSafe(schema: Schema, config: IndexConfig | null | undefined, key?: string | null): void {
  const hasConfig = config !== undefined && config !== null;
  const hasKey = key !== undefined && key !== null;
  if (!hasConfig && !hasKey) {
    throw new Error('createIndex requires an IndexConfig and/or a key');
  }
  schema.createIndex(config ?? undefined, key ?? undefined);
}

Type guard

const hasIndexTarget = (
  config?: IndexConfig | null,
  key?: string | null,
): boolean =>
  (config !== undefined && config !== null) ||
  (key !== undefined && key !== null);

Try / catch

try {
  schema.createIndex(config, key);
} catch (e) {
  if (e instanceof Error && e.message === 'Cannot enable all index types globally. Must specify either config or key.') {
    // default to a global vector index and retry
  } else {
    throw e;
  }
}

Prevention

Wrap createIndex in your own function whose parameters make the config required.
Unit-test schema assembly so empty migration steps fail in CI, not at runtime.

When it happens

Trigger: schema.createIndex(); schema.createIndex(undefined, undefined); passing a config variable that is conditionally undefined (config = cond ? cfg : undefined) while no key is given.

Common situations: Optional-index migrations that call createIndex unconditionally; copying a doc example but dropping its arguments; TypeScript not flagging it because both parameters are optional.

Related errors

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