deepset-ai/haystack · error · DeserializationError

Refusing to deserialize unknown parameter '{key}' for '{cls.

Error message

Refusing to deserialize unknown parameter '{key}' for '{cls.__name__}'. {known_params} Correct the parameter name or remove it from the serialized data.

What it means

default_from_dict() inspects the target class __init__ signature and refuses to deserialize when init_parameters contains a key that is not an accepted parameter name. This prevents silently dropping mistyped or obsolete parameters, which would otherwise change pipeline behavior unnoticed.

Source

Thrown at haystack/core/serialization.py:325

        if isinstance(value, dict) and "type" in value:
            type_value = value.get("type")
            # Special handling for Secret (type == "env_var")
            if type_value == "env_var":
                init_params[key] = Secret.from_dict(value)
            # Special handling for ComponentDevice (type == "single" or "multiple")
            elif _is_serialized_component_device(value):
                init_params[key] = ComponentDevice.from_dict(value)
            # If type looks like a fully qualified class name, try to import it and deserialize
            elif isinstance(type_value, str) and "." in type_value:
                # Reject before importing if the parent class does not accept this parameter.
                # This blocks YAML that smuggles untrusted classes into unused parameter slots.
                if valid_init_param_names is not None and key not in valid_init_param_names:
                    known_params = (
                        f"Valid parameters are: {', '.join(repr(n) for n in sorted(valid_init_param_names))}."
                        if valid_init_param_names
                        else f"'{cls.__name__}' accepts no init parameters."
                    )
                    raise DeserializationError(
                        f"Refusing to deserialize unknown parameter '{key}' for '{cls.__name__}'. {known_params} "
                        f"Correct the parameter name or remove it from the serialized data."
                    )
                try:
                    imported_class = import_class_by_name(type_value)
                    if hasattr(imported_class, "from_dict") and callable(imported_class.from_dict):
                        init_params[key] = imported_class.from_dict(value)
                    else:
                        init_params[key] = default_from_dict(imported_class, value)
                except (ImportError, DeserializationError) as e:
                    raise type(e)(f"Failed to deserialize '{key}': {e}") from e

    return cls(**init_params)


def _init_parameter_names(cls: type[object]) -> set[str] | None:
    """
    Return the set of init parameter names accepted by `cls`.

View on GitHub (pinned to e318778c9b)

Solutions

Rename the parameter to one of the listed valid names in the error message.
Remove the obsolete parameter from the serialized data if it no longer exists.
Check the component's current API docs and update the serialized config accordingly.
Regenerate the pipeline config from a working setup with pipeline.dumps().

Example fix

// before
{"type": "haystack.components.retrievers.in_memory.InMemoryBM25Retriever", "init_parameters": {"document_store": store, "top_k": 10, "scale_score": true}}  # if scale_score was removed

// after
{"type": "haystack.components.retrievers.in_memory.InMemoryBM25Retriever", "init_parameters": {"document_store": store, "top_k": 10}}

Defensive patterns

Strategy: validation

Validate before calling

import inspect
valid = set(inspect.signature(MyComponent.__init__).parameters) - {"self"}
bad = set(data.get("init_parameters", {})) - valid
assert not bad, f"unknown init params: {bad}; valid: {sorted(valid)}"

Try / catch

from haystack.core.errors import DeserializationError
try:
    comp = SomeComponent.from_dict(data)
except DeserializationError as e:
    print(e)  # message lists valid parameter names; fix init_parameters accordingly
    raise

Prevention

Regenerate pipeline configs after component upgrades instead of reusing old files
Diff init_parameters against the component's __init__ signature when hand-editing
Read the valid-parameters list in the error message and correct names accordingly

When it happens

Trigger: Loading a pipeline dict/YAML whose component init_parameters include a misspelled parameter or one removed in a newer haystack/component version, e.g. {'retriever': ...} instead of {'retrievers': ...}.

Common situations: Upgrades where a component renamed or dropped init parameters; typos in hand-edited YAML; configs generated for 1.x haystack used with 2.x components.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/58d7fb1fea618ce5. Report an issue: GitHub.