{"record":{"id":"58d7fb1fea618ce5","repo":"deepset-ai/haystack","slug":"refusing-to-deserialize-unknown-parameter-key","errorCode":null,"errorMessage":"Refusing to deserialize unknown parameter '{key}' for '{cls.__name__}'. {known_params} Correct the parameter name or remove it from the serialized data.","messagePattern":"Refusing to deserialize unknown parameter '(.+?)' for '(.+?)'\\. (.+?) Correct the parameter name or remove it from the serialized data\\.","errorType":"exception","errorClass":"DeserializationError","httpStatus":null,"severity":"error","filePath":"haystack/core/serialization.py","lineNumber":325,"sourceCode":"        if isinstance(value, dict) and \"type\" in value:\n            type_value = value.get(\"type\")\n            # Special handling for Secret (type == \"env_var\")\n            if type_value == \"env_var\":\n                init_params[key] = Secret.from_dict(value)\n            # Special handling for ComponentDevice (type == \"single\" or \"multiple\")\n            elif _is_serialized_component_device(value):\n                init_params[key] = ComponentDevice.from_dict(value)\n            # If type looks like a fully qualified class name, try to import it and deserialize\n            elif isinstance(type_value, str) and \".\" in type_value:\n                # Reject before importing if the parent class does not accept this parameter.\n                # This blocks YAML that smuggles untrusted classes into unused parameter slots.\n                if valid_init_param_names is not None and key not in valid_init_param_names:\n                    known_params = (\n                        f\"Valid parameters are: {', '.join(repr(n) for n in sorted(valid_init_param_names))}.\"\n                        if valid_init_param_names\n                        else f\"'{cls.__name__}' accepts no init parameters.\"\n                    )\n                    raise DeserializationError(\n                        f\"Refusing to deserialize unknown parameter '{key}' for '{cls.__name__}'. {known_params} \"\n                        f\"Correct the parameter name or remove it from the serialized data.\"\n                    )\n                try:\n                    imported_class = import_class_by_name(type_value)\n                    if hasattr(imported_class, \"from_dict\") and callable(imported_class.from_dict):\n                        init_params[key] = imported_class.from_dict(value)\n                    else:\n                        init_params[key] = default_from_dict(imported_class, value)\n                except (ImportError, DeserializationError) as e:\n                    raise type(e)(f\"Failed to deserialize '{key}': {e}\") from e\n\n    return cls(**init_params)\n\n\ndef _init_parameter_names(cls: type[object]) -> set[str] | None:\n    \"\"\"\n    Return the set of init parameter names accepted by `cls`.","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/core/serialization.py#L307-L343","documentation":"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.","triggerScenarios":"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': ...}.","commonSituations":"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.","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()."],"exampleFix":"// before\n{\"type\": \"haystack.components.retrievers.in_memory.InMemoryBM25Retriever\", \"init_parameters\": {\"document_store\": store, \"top_k\": 10, \"scale_score\": true}}  # if scale_score was removed\n\n// after\n{\"type\": \"haystack.components.retrievers.in_memory.InMemoryBM25Retriever\", \"init_parameters\": {\"document_store\": store, \"top_k\": 10}}","handlingStrategy":"validation","validationCode":"import inspect\nvalid = set(inspect.signature(MyComponent.__init__).parameters) - {\"self\"}\nbad = set(data.get(\"init_parameters\", {})) - valid\nassert not bad, f\"unknown init params: {bad}; valid: {sorted(valid)}\"","typeGuard":null,"tryCatchPattern":"from haystack.core.errors import DeserializationError\ntry:\n    comp = SomeComponent.from_dict(data)\nexcept DeserializationError as e:\n    print(e)  # message lists valid parameter names; fix init_parameters accordingly\n    raise","preventionTips":["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"],"tags":["deserialization","haystack","config-validation"],"backgroundTag":"unknown-init-parameter","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}