deepset-ai/haystack · error · ValueError

outputs_to_string raw_result must be a boolean.

Error message

outputs_to_string raw_result must be a boolean.

What it means

A root-level "raw_result" in outputs_to_string controls whether the raw tool result (vs. the serialized string) is used, and must be a bool. __post_init__ raises ValueError for non-boolean values like strings "true"/"false" or ints 0/1.

Source

Thrown at haystack/tools/tool.py:164

            # 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
                for key in self.outputs_to_string:
                    if key not in {"source", "handler", "raw_result"}:
                        raise ValueError(
                            "Invalid outputs_to_string config. "
                            "When using 'source', 'handler' or 'raw_result' at the root level, no other keys are "
                            " allowed. Use individual output configs instead."
                        )
            else:
                # Multiple outputs configuration
                for key, config in self.outputs_to_string.items():
                    if not isinstance(config, dict):

View on GitHub (pinned to e318778c9b)

Solutions

1. Pass a real boolean: {"raw_result": True} or False.
2. If the value comes from a config string, coerce with `str(v).lower() == "true"` or `bool(v)` (carefully) before constructing the Tool.
3. Remove "raw_result" if the default behavior is desired.

Example fix

// before
raw = os.getenv("TOOL_RAW_RESULT", "false")
outputs_to_string={"raw_result": raw}

// after
raw = os.getenv("TOOL_RAW_RESULT", "false").lower() == "true"
outputs_to_string={"raw_result": raw}

ots = outputs_to_string or {}
if "raw_result" in ots and not isinstance(ots["raw_result"], bool):
    raise TypeError("raw_result must be a bool")

def valid_raw_result(ots: dict | None) -> bool:
    v = (ots or {}).get("raw_result", True)
    return isinstance(v, bool)

try:
    tool = Tool(name="t", function=f, outputs_to_string=ots)
except ValueError as e:
    if "raw_result must be a boolean" in str(e):
        logger.error(f"Coerce raw_result to bool: {e}")
    raise

When it happens

Trigger: Tool(..., outputs_to_string={"raw_result": "true"}) or {"raw_result": 1} — truthy non-bool values from env/config parsing.

Common situations: Configs sourced from environment variables or YAML/JSON where booleans are parsed as strings; hand-built dicts using 0/1.

Related errors

• outputs_to_state configuration for key '{key}' must be a dic
• outputs_to_state source for key '{key}' must be a string.
• outputs_to_state handler for key '{key}' must be callable
• outputs_to_state: '{name}' maps state key '{state_key}' to u
• outputs_to_string source must be a string.

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