{"record":{"id":"105520e274fdc3ee","repo":"chroma-core/chroma","slug":"cannot-set-static-parameter-name","errorCode":null,"errorMessage":"Cannot set static parameter: {name}","messagePattern":"Cannot set static parameter: (.+?)","errorType":"validation","errorClass":"StaticParameterError","httpStatus":null,"severity":"error","filePath":"chromadb/api/configuration.py","lineNumber":168,"sourceCode":"        return list(self.parameter_map.values())\n\n    def get_parameter(self, name: str) -> ConfigurationParameter:\n        \"\"\"Returns the parameter with the given name, or except if it doesn't exist.\"\"\"\n        if name not in self.parameter_map:\n            raise ValueError(\n                f\"Invalid parameter name: {name} for configuration {self.__class__.__name__}\"\n            )\n        param_value = cast(ConfigurationParameter, self.parameter_map.get(name))\n        return param_value\n\n    def set_parameter(self, name: str, value: Union[str, int, float, bool]) -> None:\n        \"\"\"Sets the parameter with the given name to the given value.\"\"\"\n        if name not in self.definitions:\n            raise ValueError(f\"Invalid parameter name: {name}\")\n        definition = self.definitions[name]\n        parameter = self.parameter_map[name]\n        if definition.is_static:\n            raise StaticParameterError(f\"Cannot set static parameter: {name}\")\n        if not definition.validator(value):\n            raise ValueError(f\"Invalid value for parameter {name}: {value}\")\n        parameter.value = value\n\n    @override\n    def to_json_str(self) -> str:\n        \"\"\"Returns the JSON representation of the configuration.\"\"\"\n        return json.dumps(self.to_json())\n\n    @classmethod\n    @override\n    def from_json_str(cls, json_str: str) -> Self:\n        \"\"\"Returns a configuration from the given JSON string.\"\"\"\n        try:\n            config_json = json.loads(json_str)\n        except json.JSONDecodeError:\n            raise ValueError(\n                f\"Unable to decode configuration from JSON string: {json_str}\"","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/configuration.py#L150-L186","documentation":"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\".","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check mutability first: `if cfg.definitions[name].is_static:` rebuild instead of set","Recreate the collection (or the index) with the new value - chromadb has no in-place mutation for static parameters","Filter static keys out of dynamic-update paths and route them to your provisioning or rebuild flow"],"exampleFix":"# before\ncfg.set_parameter(\"space\", \"cosine\")   # StaticParameterError if static\n# after\nif cfg.definitions[\"space\"].is_static:\n    client.delete_collection(\"docs\")\n    col = client.create_collection(\n        \"docs\", configuration=HNSWConfigurationInterface(space=\"cosine\"))\nelse:\n    cfg.set_parameter(\"space\", \"cosine\")","handlingStrategy":"try-catch","validationCode":"def set_if_mutable(cfg, name, value):\n    d = cfg.definitions[name]\n    if d.is_static:\n        return False            # caller must recreate the collection/index instead\n    cfg.set_parameter(name, value)\n    return True","typeGuard":null,"tryCatchPattern":"from chromadb.api.configuration import StaticParameterError\n\ntry:\n    cfg.set_parameter(name, value)\nexcept StaticParameterError:\n    # structural parameter: schedule a collection rebuild with the new value\n    rebuild_queue.put((name, value))","preventionTips":["Inspect cfg.definitions[name].is_static before mutating","Treat static parameters as provisioning inputs (set at creation time), not runtime knobs","Catch StaticParameterError separately from ValueError in dynamic-update code"],"tags":["chromadb","configuration","static-parameter","immutability","hnsw"],"backgroundTag":"configuration-validation-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}