deepset-ai/haystack · error · ValueError

outputs_to_state: '{name}' maps state key '{state_key}' to u

Error message

outputs_to_state: '{name}' maps state key '{state_key}' to unknown output '{source}'Valid outputs are: {valid_outputs}.

What it means

outputs_to_state entries with a "source" must reference an output the tool actually produces. __post_init__ computes the set of valid outputs (from the function signature/outputs) and raises ValueError when a source name is unknown, listing the valid outputs.

Source

Thrown at haystack/tools/tool.py:153

            raise ValueError("The provided parameters do not define a valid JSON schema") from e

        # Validate outputs structure if provided
        if self.outputs_to_state is not None:
            for key, config in self.outputs_to_state.items():
                if not isinstance(config, dict):
                    raise TypeError(f"outputs_to_state configuration for key '{key}' must be a dictionary")
                if "source" in config and not isinstance(config["source"], str):
                    raise ValueError(f"outputs_to_state source for key '{key}' must be a string.")
                if "handler" in config and not callable(config["handler"]):
                    raise ValueError(f"outputs_to_state handler for key '{key}' must be callable")

            # Validate that outputs_to_state source keys exist as valid tool outputs
            valid_outputs: set[str] | None = self._get_valid_outputs()
            if valid_outputs is not None:
                for state_key, config in self.outputs_to_state.items():
                    source = config.get("source")
                    if source is not None and source not in valid_outputs:
                        raise ValueError(
                            f"outputs_to_state: '{self.name}' maps state key '{state_key}' to unknown output '{source}'"
                            f"Valid outputs are: {valid_outputs}."
                        )

        if self.outputs_to_string is not None:
            if "source" in self.outputs_to_string and not isinstance(self.outputs_to_string["source"], str):
                raise ValueError("outputs_to_string source must be a string.")
            if "handler" in self.outputs_to_string and not callable(self.outputs_to_string["handler"]):
                raise ValueError("outputs_to_string handler must be callable")
            if "raw_result" in self.outputs_to_string and not isinstance(self.outputs_to_string["raw_result"], bool):
                raise ValueError("outputs_to_string raw_result must be a boolean.")

            if (
                "source" in self.outputs_to_string
                or "handler" in self.outputs_to_string
                or "raw_result" in self.outputs_to_string
            ):
                # Single output configuration

View on GitHub (pinned to e318778c9b)

Solutions

1. Change "source" to one of the listed valid outputs in the error message.
2. Update the tool function's declared outputs to include the referenced name if that output is intended.
3. Run the Tool construction in a test so the mismatch fails fast at init rather than at pipeline runtime.

Example fix

// before
Tool(name="retriever", function=retrieve, outputs_to_state={"k": {"source": "results"}})

// after
Tool(name="retriever", function=retrieve, outputs_to_state={"k": {"source": "documents"}})  # valid output

valid = {"documents", "answer"}  # tool's declared outputs
for k, cfg in outputs_to_state.items():
    src = cfg.get("source")
    assert src is None or src in valid, f"'{src}' not in tool outputs {valid}"

try:
    tool = Tool(name="t", function=f, outputs_to_state=ots)
except ValueError as e:
    if "unknown output" in str(e):
        logger.error(e)  # message lists the valid outputs
    raise

When it happens

Trigger: Tool(..., outputs_to_state={"k": {"source": "results"}}) while the tool function is declared to produce outputs like ["documents", "answer"] — any typo'd or stale output name.

Common situations: Renaming a tool's outputs (or changing the decorated function's return signature) without updating outputs_to_state; copy-pasting configs between similar tools; mixing up parameter names with output names.

Related errors

• outputs_to_state source for key '{key}' must be a string.
• outputs_to_string source must be a string.
• Invalid outputs_to_string config. When using 'source', 'hand
• top_k must be greater than 0.
• `async_function` must be a coroutine function defined with `

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