chroma-core/chroma · error · ValueError

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

Error message

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

What it means

ChromaBm25EmbeddingFunction.validate_config_update rejects any embedding-function config update that contains a key outside the mutable set {k, b, avg_doc_length, token_max_length, stopwords, include_tokens}. Chroma enforces this because the BM25 sparse embedding function only supports live-tuning those six parameters; changing any other key would silently alter the function identity. The offender key name and the function name 'chroma_bm25' are interpolated into the message.

Source

Thrown at chromadb/utils/embedding_functions/chroma_bm25_embedding_function.py:174

        if self.stopwords is not None:
            config["stopwords"] = list(self.stopwords)

        return config

    def validate_config_update(
        self, old_config: Dict[str, Any], new_config: Dict[str, Any]
    ) -> None:
        mutable_keys = {
            "k",
            "b",
            "avg_doc_length",
            "token_max_length",
            "stopwords",
            "include_tokens",
        }
        for key in new_config:
            if key not in mutable_keys:
                raise ValueError(f"Updating '{key}' is not supported for {NAME}")

    @staticmethod
    def validate_config(config: Dict[str, Any]) -> None:
        validate_config_schema(config, NAME)

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Remove the offending key named in the message from the update dict; only the six mutable keys are accepted.
2. Fix key spelling: the mutable keys are exactly k, b, avg_doc_length, token_max_length, stopwords, include_tokens.
3. If you truly need to change the embedding function identity, create a new collection with the desired function and re-ingest.
4. Validate against ChromaBm25Config (TypedDict) or validate_config_schema(config, 'chroma_bm25') before submitting.

Example fix

# before
new_config = {"k": 1.5, "stop_words": ["the"]}  # ValueError: Updating 'stop_words' is not supported

# after
new_config = {"k": 1.5, "stopwords": ["the"]}  # only k, b, avg_doc_length, token_max_length, stopwords, include_tokens

BM25_MUTABLE = {"k", "b", "avg_doc_length", "token_max_length", "stopwords", "include_tokens"}
invalid = set(new_config) - BM25_MUTABLE
if invalid:
    raise KeyError(f"chroma_bm25 does not support updating: {sorted(invalid)}")

def is_valid_bm25_update(new_config: dict) -> bool:
    return set(new_config) <= {"k", "b", "avg_doc_length", "token_max_length", "stopwords", "include_tokens"}

try:
    ef.validate_config_update(old_config, new_config)
except ValueError as e:
    # strip the offending key named in the message and retry, or abort
    raise

When it happens

Trigger: Calling the EF config-update flow (e.g. collection.modify / embedding_function update with new_config) where new_config contains any key other than k, b, avg_doc_length, token_max_length, stopwords, include_tokens. Example: passing {"stop_words": [...]} (typo of "stopwords") or an extra key like "name".

Common situations: Persisted BM25 configs written by an older chromadb version that carried extra keys; hand-built config dicts with misspelled keys (stop_words vs stopwords); attempting to switch a collection from BM25 to another function by editing its config instead of recreating the collection.

Related errors

• Could not build embedding function {ef_config['name']} from
• The model cannot be changed after the embedding function has
• The task cannot be changed after the embedding function has
• The instructions cannot be changed after the embedding funct
• The model cannot be changed after the embedding function has

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