deepset-ai/haystack · error · ValueError

Missing required input variables in PromptBuilder: {missing_

Error message

Missing required input variables in PromptBuilder: {missing_vars_str}. Required variables: {required_variables}. Provided variables: {provided_variables}.

What it means

PromptBuilder._validate_variables (called from run) verifies that all required template variables were provided before rendering the Jinja string template. Missing variables raise ValueError with the missing/required/provided lists.

Source

Thrown at haystack/components/builders/prompt_builder.py:267

        return {"prompt": result}

    def _validate_variables(self, provided_variables: set[str]) -> None:
        """
        Checks if all the required template variables are provided.

        :param provided_variables:
            A set of provided template variables.
        :raises ValueError:
            If any of the required template variables is not provided.
        """
        if self.required_variables == "*":
            required_variables = sorted(self.variables)
        else:
            required_variables = self.required_variables
        missing_variables = [var for var in required_variables if var not in provided_variables]
        if missing_variables:
            missing_vars_str = ", ".join(missing_variables)
            raise ValueError(
                f"Missing required input variables in PromptBuilder: {missing_vars_str}. "
                f"Required variables: {required_variables}. Provided variables: {provided_variables}."
            )

View on GitHub (pinned to e318778c9b)

Solutions

1. Supply the missing variables in the run() kwargs as listed in the error.
2. Align the builder's variables/required_variables with what callers actually provide.
3. Remove stale placeholders from the template string.

Example fix

// before
prompt_builder.run(question=q)
// after
prompt_builder.run(question=q, context=docs)

required = set(builder.required_variables or builder.variables or [])
missing = required - set(kwargs)
assert not missing, f'missing template vars: {missing}'

def has_required_vars(builder, kwargs: dict) -> bool:
    required = set(builder.required_variables or builder.variables or [])
    return required.issubset(kwargs.keys())

try:
    res = builder.run(**kwargs)
except ValueError as e:
    if 'Missing required input variables in PromptBuilder' in str(e):
        kwargs.update(default_variables)
        res = builder.run(**kwargs)
    else:
        raise

When it happens

Trigger: Calling PromptBuilder.run(question=q) on a builder whose template contains more placeholders (e.g. {{ context }}) than were supplied.

Common situations: Template edited to add a variable without updating run() callsites; pipeline input not connected; variables= list on the builder enumerating names the caller never passes.

Related errors

• Missing required input variables in ChatPromptBuilder: {miss
• Hook of type '{type(h).__name__}' is registered under hook p
• Tool execution requires at least one tool.
• The following tool names are not valid: {invalid_tool_names}
• user_prompt must define exactly one message block, found {le

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