chroma-core/chroma · error

Updating '${key}' is not supported for ${NAME}

Error message

Updating '${key}' is not supported for ${NAME}

What it means

Thrown by ChromaBm25EmbeddingFunction.validateConfigUpdate when a config update payload contains any key outside the mutable set {k, b, avg_doc_length, token_max_length, stopwords}. BM25 is a stateless algorithm whose structural fields cannot be rebuilt from stored data, so Chroma restricts updates to the scoring parameters; any other key (immutable like a model, or simply unknown/typo'd) is rejected.

Source

Thrown at clients/new-js/packages/ai-embeddings/chroma-bm25/src/index.ts:270

        const config: ChromaBm25Config = {
            k: this.k,
            b: this.b,
            avg_doc_length: this.avgDocLength,
            token_max_length: this.tokenMaxLength,
        };

        if (this.customStopwords) {
            config.stopwords = [...this.customStopwords];
        }

        return config;
    }

    public validateConfigUpdate(newConfig: Record<string, unknown>): void {
        const mutableKeys = new Set(["k", "b", "avg_doc_length", "token_max_length", "stopwords"]);
        for (const key of Object.keys(newConfig)) {
            if (!mutableKeys.has(key)) {
                throw new Error(`Updating '${key}' is not supported for ${NAME}`);
            }
        }
    }

    public static validateConfig(config: ChromaBm25Config): void {
        validateConfigSchema(config, NAME);
    }
}

// register with both name (chroma_bm25) and mapped package name (chroma-bm25)
registerSparseEmbeddingFunction(NAME, ChromaBm25EmbeddingFunction);
registerSparseEmbeddingFunction("chroma-bm25", ChromaBm25EmbeddingFunction);

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Send only the mutable keys you actually want to change: k, b, avg_doc_length, token_max_length, stopwords.
2. Use snake_case exactly as listed (avg_doc_length, not avgDocLength).
3. If you need a fundamentally different configuration, create a new collection with a new embedding function instead of updating.
4. Log Object.keys(newConfig) before updating to spot stray/typo'd keys.

Example fix

// before
await collection.modify({
  embedding_function: { name: "chroma_bm25", config: { k: 1.5, model: "bm25" } }, // 'model' not mutable
});

// after
await collection.modify({
  embedding_function: { name: "chroma_bm25", config: { k: 1.5 } },
});

const BM25_MUTABLE = new Set(["k", "b", "avg_doc_length", "token_max_length", "stopwords"]);
const patch = { k: 1.5 }; // your intended changes
const illegal = Object.keys(patch).filter((k) => !BM25_MUTABLE.has(k));
if (illegal.length > 0) {
  throw new Error(`Non-updatable BM25 keys: ${illegal.join(", ")}`);
}
// then perform the config update

function isBm25MutableConfig(c: Record<string, unknown>): boolean {
  return Object.keys(c).every((k) =>
    ["k", "b", "avg_doc_length", "token_max_length", "stopwords"].includes(k),
  );
}

When it happens

Trigger: Updating the sparse embedding function config with an unrecognized or immutable key, e.g. { model: ... } or a camelCase typo like { avgDocLength: 300 }; copy-pasting a full config object (including read-only fields) into an update call instead of only changed fields.

Common situations: Porting Python chromadb config-update code that passes whole config dicts; using camelCase keys instead of the snake_case config schema (avg_doc_length, token_max_length); attempting to change fields that must stay fixed for consistency with existing indexed data.

Related errors

• The model name cannot be changed after initialization.
• The task type cannot be changed after initialization.
• Changing the URL is not allowed.
• Cannot change model name.
• Config is missing a required field

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