{"record":{"id":"1184005177bad2d8","repo":"deepset-ai/haystack","slug":"items-in-the-tools-list-must-be-tool-or-toolset-in","errorCode":null,"errorMessage":"Items in the tools list must be Tool or Toolset instances.","messagePattern":"Items in the tools list must be Tool or Toolset instances\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"haystack/tools/serde_utils.py","lineNumber":33,"sourceCode":"\ndef serialize_tools_or_toolset(tools: \"ToolsType | None\") -> dict[str, Any] | list[dict[str, Any]] | None:\n    \"\"\"\n    Serialize tools or toolsets to dictionaries.\n\n    :param tools: A Toolset, a list of Tools and/or Toolsets, or None\n    :returns: Serialized representation preserving Tool/Toolset boundaries when provided\n    \"\"\"\n    if tools is None:\n        return None\n    if isinstance(tools, Toolset):\n        return tools.to_dict()\n    if isinstance(tools, list):\n        serialized: list[dict[str, Any]] = []\n        for item in tools:\n            if isinstance(item, (Toolset, Tool)):\n                serialized.append(item.to_dict())\n            else:\n                raise TypeError(\"Items in the tools list must be Tool or Toolset instances.\")\n        return serialized\n    raise TypeError(\"tools must be Toolset, list[Union[Tool, Toolset]], or None\")\n\n\ndef deserialize_tools_or_toolset_inplace(data: dict[str, Any], key: str = \"tools\") -> None:\n    \"\"\"\n    Deserialize a list of Tools and/or Toolsets, or a single Toolset in a dictionary inplace.\n\n    :param data:\n        The dictionary with the serialized data.\n    :param key:\n        The key in the dictionary where the list of Tools and/or Toolsets, or single Toolset is stored.\n    \"\"\"\n    if key in data:\n        serialized_tools = data[key]\n\n        if serialized_tools is None:\n            return","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/tools/serde_utils.py#L15-L51","documentation":"serialize_tools_or_toolset in haystack/tools/serde_utils.py serializes toolsets and tool lists for pipeline serialization (to_dict). When given a list, each item must be a Tool or Toolset and is serialized via its to_dict(); any other item raises TypeError. This guards pipeline save/loading against corrupted tool registries.","triggerScenarios":"Calling to_dict() on a Toolset/serializable component whose tools list contains non-Tool/non-Toolset items (dicts, raw callables, None, partially constructed objects).","commonSituations":"Manually building a tools list and inserting raw dicts or un-instantiated factories; deserialization bugs that left placeholders in the list; passing a single Tool (not in a list) with the list-handling path expected.","solutions":["Ensure every element of the tools list is an instantiated Tool or Toolset before serializing","Replace raw dict representations with proper Tool.from_dict(...) / Toolset instances","Filter out None or placeholder entries before to_dict()","If you have a single Tool, confirm you're using the intended Toolset/Tool to_dict path"],"exampleFix":"// before\ntoolset.to_dict()  # tools contains raw dicts\n\n// after\ntools = [Tool.from_dict(d) if isinstance(d, dict) else d for d in raw_tools]\nts = Toolset(tools=tools)\nts.to_dict()","handlingStrategy":"validation","validationCode":"from haystack.tools import Tool, Toolset\n\ndef validate_serializable_tools(tools) -> None:\n    if tools is None or isinstance(tools, Toolset):\n        return\n    for i, item in enumerate(tools):\n        if not isinstance(item, (Tool, Toolset)):\n            raise TypeError(f\"tools[{i}] is {type(item).__name__}; must be Tool or Toolset before to_dict()\")","typeGuard":"def is_serializable_tools_list(tools) -> bool:\n    from haystack.tools import Tool, Toolset\n    return tools is None or isinstance(tools, Toolset) or (\n        isinstance(tools, list) and all(isinstance(i, (Tool, Toolset)) for i in tools)\n    )","tryCatchPattern":"try:\n    data = toolset.to_dict()\nexcept TypeError as e:\n    logger.error(\"Tool registry corrupted for serialization: %s\", e)\n    raise","preventionTips":["Only insert instantiated Tool/Toolset objects into tools lists","Rehydrate raw dicts with Tool.from_dict before registering","Validate the tools list before any pipeline to_dict()/dump operation"],"tags":["serialization","type-check","toolset"],"backgroundTag":"invalid-serialization-type","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}