chroma-core/chroma · error · ValueError

Invalid parameter name: {parameter.name}

Error message

Invalid parameter name: {parameter.name}

What it means

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.

Source

Thrown at chromadb/api/configuration.py:105

T = TypeVar("T", bound="ConfigurationInternal")


class ConfigurationInternal(JSONSerializable["ConfigurationInternal"]):
    """Represents an abstract configuration, used internally by Chroma."""

    # The internal data structure used to store the parameters
    # All expected parameters must be present with defaults or None values at initialization
    parameter_map: Dict[str, ConfigurationParameter]
    definitions: ClassVar[Dict[str, ConfigurationDefinition]]

    def __init__(self, parameters: Optional[List[ConfigurationParameter]] = None):
        """Initializes a new instance of the Configuration class. Respecting defaults and
        validators."""
        self.parameter_map = {}
        if parameters is not None:
            for parameter in parameters:
                if parameter.name not in self.definitions:
                    raise ValueError(f"Invalid parameter name: {parameter.name}")

                definition = self.definitions[parameter.name]
                # Handle the case where we have a recursive configuration definition
                if isinstance(parameter.value, dict):
                    child_type = globals().get(parameter.value.get("_type", None))
                    if child_type is None:
                        raise ValueError(
                            f"Invalid configuration type: {parameter.value}"
                        )
                    parameter.value = child_type.from_json(parameter.value)
                if not isinstance(parameter.value, type(definition.default_value)):
                    raise ValueError(f"Invalid parameter value: {parameter.value}")

                parameter_validator = definition.validator
                if not parameter_validator(parameter.value):
                    raise ValueError(f"Invalid parameter value: {parameter.value}")
                self.parameter_map[parameter.name] = parameter
        # Apply the defaults for any missing parameters

View on GitHub (pinned to aecdd12c8a)

Solutions

1. List the accepted names before constructing: sorted(Cls.definitions.keys()) and fix the offending name
2. If the config came from JSON, strip unknown keys or reconcile versions so producer and consumer agree on names
3. Use the documented public interface (e.g. HNSWConfigurationInterface constructor) instead of raw ConfigurationParameter lists

Example fix

# before
params = [ConfigurationParameter(name="ef", value=200)]
cfg = HNSWConfigurationInternal(parameters=params)   # "ef" unknown
# after
print(sorted(HNSWConfigurationInternal.definitions))  # see valid names
params = [ConfigurationParameter(name="ef_search", value=200)]
cfg = HNSWConfigurationInternal(parameters=params)

def filter_known(cls, parameters):
    known = set(cls.definitions)
    unknown = [p.name for p in parameters if p.name not in known]
    if unknown:
        raise ValueError(f"unknown parameter names {unknown}; valid: {sorted(known)}")
    return parameters

try:
    cfg = Cls(parameters=params)
except ValueError as e:
    if "Invalid parameter name" in str(e):
        params = [p for p in params if p.name in Cls.definitions]
        cfg = Cls(parameters=params)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid configuration type: {parameter.value}
• Invalid parameter value: {parameter.value}
• Invalid parameter name: {name} for configuration {self.__cla
• Invalid parameter name: {name}
• Trying to instantiate configuration of type {cls.__name__} f

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