{"record":{"id":"5788e33fb2d19ff7","repo":"chroma-core/chroma","slug":"invalid-parameter-name-parameter-name","errorCode":null,"errorMessage":"Invalid parameter name: {parameter.name}","messagePattern":"Invalid parameter name: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/configuration.py","lineNumber":105,"sourceCode":"T = TypeVar(\"T\", bound=\"ConfigurationInternal\")\n\n\nclass ConfigurationInternal(JSONSerializable[\"ConfigurationInternal\"]):\n    \"\"\"Represents an abstract configuration, used internally by Chroma.\"\"\"\n\n    # The internal data structure used to store the parameters\n    # All expected parameters must be present with defaults or None values at initialization\n    parameter_map: Dict[str, ConfigurationParameter]\n    definitions: ClassVar[Dict[str, ConfigurationDefinition]]\n\n    def __init__(self, parameters: Optional[List[ConfigurationParameter]] = None):\n        \"\"\"Initializes a new instance of the Configuration class. Respecting defaults and\n        validators.\"\"\"\n        self.parameter_map = {}\n        if parameters is not None:\n            for parameter in parameters:\n                if parameter.name not in self.definitions:\n                    raise ValueError(f\"Invalid parameter name: {parameter.name}\")\n\n                definition = self.definitions[parameter.name]\n                # Handle the case where we have a recursive configuration definition\n                if isinstance(parameter.value, dict):\n                    child_type = globals().get(parameter.value.get(\"_type\", None))\n                    if child_type is None:\n                        raise ValueError(\n                            f\"Invalid configuration type: {parameter.value}\"\n                        )\n                    parameter.value = child_type.from_json(parameter.value)\n                if not isinstance(parameter.value, type(definition.default_value)):\n                    raise ValueError(f\"Invalid parameter value: {parameter.value}\")\n\n                parameter_validator = definition.validator\n                if not parameter_validator(parameter.value):\n                    raise ValueError(f\"Invalid parameter value: {parameter.value}\")\n                self.parameter_map[parameter.name] = parameter\n        # Apply the defaults for any missing parameters","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/configuration.py#L87-L123","documentation":"ConfigurationInternal.__init__ (chromadb/api/configuration.py:105) raises this when a ConfigurationParameter is supplied whose name is not in that configuration class's definitions dict. Every parameter must be pre-declared with a default, validator, and static flag on the class; the constructor is strict by design so typos and unknown keys from deserialized JSON fail fast instead of being silently ignored.","triggerScenarios":"Building a Configuration subclass (e.g. HNSWConfigurationInternal) with ConfigurationParameter(name=\"ef\", value=200) when the declared name is \"ef_construction\"; calling from_json()/from_json_str() on a dict containing keys absent from definitions; loading config JSON written by a different chromadb version that declared different parameter names.","commonSituations":"Version skew: config JSON persisted by an older or newer chromadb with renamed parameters; hand-edited settings files or hand-built parameter lists with typos or casing mistakes; migration code passing legacy names directly instead of via from_legacy_params.","solutions":["List the accepted names before constructing: sorted(Cls.definitions.keys()) and fix the offending name","If the config came from JSON, strip unknown keys or reconcile versions so producer and consumer agree on names","Use the documented public interface (e.g. HNSWConfigurationInterface constructor) instead of raw ConfigurationParameter lists"],"exampleFix":"# before\nparams = [ConfigurationParameter(name=\"ef\", value=200)]\ncfg = HNSWConfigurationInternal(parameters=params)   # \"ef\" unknown\n# after\nprint(sorted(HNSWConfigurationInternal.definitions))  # see valid names\nparams = [ConfigurationParameter(name=\"ef_search\", value=200)]\ncfg = HNSWConfigurationInternal(parameters=params)","handlingStrategy":"validation","validationCode":"def filter_known(cls, parameters):\n    known = set(cls.definitions)\n    unknown = [p.name for p in parameters if p.name not in known]\n    if unknown:\n        raise ValueError(f\"unknown parameter names {unknown}; valid: {sorted(known)}\")\n    return parameters","typeGuard":null,"tryCatchPattern":"try:\n    cfg = Cls(parameters=params)\nexcept ValueError as e:\n    if \"Invalid parameter name\" in str(e):\n        params = [p for p in params if p.name in Cls.definitions]\n        cfg = Cls(parameters=params)\n    else:\n        raise","preventionTips":["Validate names against Cls.definitions before constructing","Prefer the public interface constructors over raw parameter lists","Regenerate stored config JSON with the same chromadb version that reads it"],"tags":["chromadb","configuration","parameter-names","serialization"],"backgroundTag":"configuration-validation-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}