{"record":{"id":"166411688696d83d","repo":"deepset-ai/haystack","slug":"state-key-key-not-found-in-schema-schema-s","errorCode":null,"errorMessage":"State: Key '{key}' not found in schema. Schema: {self.schema}","messagePattern":"State: Key '(.+?)' not found in schema\\. Schema: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/components/agents/state/state.py","lineNumber":169,"sourceCode":"        \"\"\"\n        return deepcopy(self._data.get(key, default))\n\n    def set(self, key: str, value: Any, handler_override: Callable[[Any, Any], Any] | None = None) -> None:\n        \"\"\"\n        Set or merge a value in the state according to schema rules.\n\n        Value is merged or overwritten according to these rules:\n          - if handler_override is given, use that\n          - else use the handler defined in the schema for 'key'\n\n        :param key: Key to store the value under\n        :param value: Value to store or merge\n        :param handler_override: Optional function to override the default merge behavior\n        \"\"\"\n        # If key not in schema, we throw an error\n        definition = self.schema.get(key, None)\n        if definition is None:\n            raise ValueError(f\"State: Key '{key}' not found in schema. Schema: {self.schema}\")\n\n        # Get current value from state and apply handler\n        current_value = self._data.get(key, None)\n        handler = handler_override or definition[\"handler\"]\n        self._data[key] = handler(current_value, value)\n\n    @property\n    def data(self) -> dict[str, Any]:\n        \"\"\"\n        All current data of the state.\n        \"\"\"\n        return self._data\n\n    def has(self, key: str) -> bool:\n        \"\"\"\n        Check if a key exists in the state.\n\n        :param key: Key to check for existence","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/agents/state/state.py#L151-L187","documentation":"State.set raises this ValueError when the key being written is not present in the State's schema. The schema is closed: only keys declared at construction can be set, which keeps merges deterministic.","triggerScenarios":"Calling state.set(\"foo\", value) where 'foo' was not declared in the schema passed to State/Agent; a tool output mapping writing an undeclared key; state_schema omitting a key that tools emit.","commonSituations":"Adding a new tool whose output mapping targets a state key not added to the Agent's state_schema, or renaming a schema key without updating tool configs.","solutions":["Add the missing key to the state schema, e.g. {\"foo\": {\"type\": list}}","Check tool output {\"state_key\": ...} mappings against the schema keys","If the key shouldn't persist, return it only in the tool's string output instead of merging into state"],"exampleFix":"// before\nagent = Agent(..., state_schema={\"messages\": {\"type\": list[ChatMessage]}})\n# tool writes state_key=\"results\"\n// after\nagent = Agent(..., state_schema={\"messages\": {\"type\": list[ChatMessage]}, \"results\": {\"type\": list}})","handlingStrategy":"validation","validationCode":"def keys_in_schema(keys, schema):\n    missing = [k for k in keys if k not in schema]\n    if missing:\n        raise KeyError(f\"Keys not in schema: {missing}\")","typeGuard":"def key_is_declared(key, schema) -> bool:\n    return key in schema","tryCatchPattern":"try:\n    state.set(key, value)\nexcept ValueError as e:\n    if \"not found in schema\" in str(e):\n        state = State({**state.schema, key: {\"type\": type(value), \"handler\": None}}, state._data)\n        state.set(key, value)\n    else:\n        raise","preventionTips":["Keep tool outputs_to_state keys and state_schema keys in sync; test them together","Before adding a schema key, grep tool configs for the state_key","Add a startup assertion that all tool state keys exist in the schema"],"tags":["python","agent","state","key-not-found"],"backgroundTag":"schema-key-missing","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}