deepset-ai/haystack · error · ValueError

The provided parameters do not define a valid JSON schema

Error message

The provided parameters do not define a valid JSON schema

What it means

The Tool's `parameters` must be a valid JSON Schema draft 2020-12. __post_init__ runs jsonschema's Draft202012Validator.check_schema and raises ValueError (chaining the SchemaError) if the schema itself is malformed, so that invalid tool signatures fail fast at construction time.

Source

Thrown at haystack/tools/tool.py:135

        if self.function is not None and inspect.iscoroutinefunction(self.function):
            raise ValueError(
                f"`function` must be a synchronous function. "
                f"The function '{self.function.__name__}' is a coroutine function. "
                f"Pass it as `async_function` instead."
            )

        # `async_function` must be a coroutine function defined with `async def`.
        if self.async_function is not None and not inspect.iscoroutinefunction(self.async_function):
            raise ValueError(
                f"`async_function` must be a coroutine function defined with `async def`. "
                f"Got '{getattr(self.async_function, '__name__', repr(self.async_function))}'."
            )

        # Check that the parameters define a valid JSON schema
        try:
            Draft202012Validator.check_schema(self.parameters)
        except SchemaError as e:
            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(

View on GitHub (pinned to e318778c9b)

Solutions

1. Fix the schema so it passes Draft202012Validator.check_schema (run this check standalone to see the chained SchemaError details).
2. Correct common typos: "type": "object", "properties": {<name>: {...}}, "required": [list of strings].
3. If a schema string is available, json.loads it into a dict before constructing the Tool.
4. Simplify to a minimal valid schema: {"type": "object", "properties": {...}} and build up incrementally, validating each step.

Example fix

// before
Tool(name="search", function=search, parameters={"type": "objct", "properties": {"q": {"type": "string"}}})

// after
Tool(name="search", function=search, parameters={"type": "object", "properties": {"q": {"type": "string"}}, "required": ["q"]})

from jsonschema import Draft202012Validator
Draft202012Validator.check_schema(params)  # raises SchemaError before Tool construction

import json
from typing import Any

def is_valid_schema(params: Any) -> bool:
    if not isinstance(params, dict):
        return False
    try:
        Draft202012Validator.check_schema(params)
        return True
    except Exception:
        return False

try:
    tool = Tool(name="t", function=f, parameters=params)
except ValueError as e:
    logger.error(f"Invalid JSON schema for tool parameters: {e.__cause__}")
    raise

When it happens

Trigger: Tool(name=..., function=..., parameters=<dict that violates meta-schema>) e.g. parameters={"type": "objct"}, missing "type"/"properties" structure, wrong types like "properties": ["a"], or not a dict at all (parameters=None or a JSON string).

Common situations: Hand-writing JSON schemas with typos; copying schemas from OpenAI/Anthropic docs using unsupported or older keywords; LLM-generated schema snippets pasted in; passing a JSON string instead of a parsed dict.

Related errors

• `async_function` must be a coroutine function defined with `
• outputs_to_state source for key '{key}' must be a string.
• outputs_to_state: '{name}' maps state key '{state_key}' to u
• outputs_to_string source must be a string.
• Invalid outputs_to_string config. When using 'source', 'hand

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