chroma-core/chroma · error · StaticParameterError

Cannot set static parameter: {name}

Error message

Cannot set static parameter: {name}

What it means

ConfigurationInternal.set_parameter (chromadb/api/configuration.py:168) raises StaticParameterError when the target parameter's definition has is_static=True. Static parameters are fixed when the owning object (e.g. a collection's index) is created and cannot be mutated afterwards; the dedicated exception type (not a ValueError subclass) lets callers distinguish "never changeable" from "bad value".

Source

Thrown at chromadb/api/configuration.py:168

        return list(self.parameter_map.values())

    def get_parameter(self, name: str) -> ConfigurationParameter:
        """Returns the parameter with the given name, or except if it doesn't exist."""
        if name not in self.parameter_map:
            raise ValueError(
                f"Invalid parameter name: {name} for configuration {self.__class__.__name__}"
            )
        param_value = cast(ConfigurationParameter, self.parameter_map.get(name))
        return param_value

    def set_parameter(self, name: str, value: Union[str, int, float, bool]) -> None:
        """Sets the parameter with the given name to the given value."""
        if name not in self.definitions:
            raise ValueError(f"Invalid parameter name: {name}")
        definition = self.definitions[name]
        parameter = self.parameter_map[name]
        if definition.is_static:
            raise StaticParameterError(f"Cannot set static parameter: {name}")
        if not definition.validator(value):
            raise ValueError(f"Invalid value for parameter {name}: {value}")
        parameter.value = value

    @override
    def to_json_str(self) -> str:
        """Returns the JSON representation of the configuration."""
        return json.dumps(self.to_json())

    @classmethod
    @override
    def from_json_str(cls, json_str: str) -> Self:
        """Returns a configuration from the given JSON string."""
        try:
            config_json = json.loads(json_str)
        except json.JSONDecodeError:
            raise ValueError(
                f"Unable to decode configuration from JSON string: {json_str}"

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Check mutability first: `if cfg.definitions[name].is_static:` rebuild instead of set
2. Recreate the collection (or the index) with the new value - chromadb has no in-place mutation for static parameters
3. Filter static keys out of dynamic-update paths and route them to your provisioning or rebuild flow

Example fix

# before
cfg.set_parameter("space", "cosine")   # StaticParameterError if static
# after
if cfg.definitions["space"].is_static:
    client.delete_collection("docs")
    col = client.create_collection(
        "docs", configuration=HNSWConfigurationInterface(space="cosine"))
else:
    cfg.set_parameter("space", "cosine")

def set_if_mutable(cfg, name, value):
    d = cfg.definitions[name]
    if d.is_static:
        return False            # caller must recreate the collection/index instead
    cfg.set_parameter(name, value)
    return True

from chromadb.api.configuration import StaticParameterError

try:
    cfg.set_parameter(name, value)
except StaticParameterError:
    # structural parameter: schedule a collection rebuild with the new value
    rebuild_queue.put((name, value))

When it happens

Trigger: Calling set_parameter on a parameter declared with is_static=True in definitions (e.g. HNSW structural options like the space function or M on an existing collection) after the collection or index already exists.

Common situations: Trying to retune an existing collection's HNSW structure at runtime; applying a settings dict to a live collection where some keys are structural; dynamic config-update loops that do not know which fields are static.

Related errors

• batch_size must be less than or equal to sync_threshold
• Invalid legacy HNSW parameter name: {name}
• Cannot specify both 'hnsw' and 'spann' configurations during
• Invalid HNSW config provided in CreateCollectionConfiguratio
• Cannot specify both 'hnsw' and 'spann' configurations during

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