deepset-ai/haystack · error · ValueError

Missing required input variables in ChatPromptBuilder: {miss

Error message

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

What it means

ChatPromptBuilder._validate_variables (called from run) checks that every required template variable is present in the provided inputs. If any are missing, it raises ValueError listing the missing, required, and provided variable names.

Source

Thrown at haystack/components/builders/chat_prompt_builder.py:317

        return messages

    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 no template is provided or if all the required template variables are 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 ChatPromptBuilder: {missing_vars_str}. "
                f"Required variables: {required_variables}. Provided variables: {provided_variables}."
            )

    def to_dict(self) -> dict[str, Any]:
        """
        Returns a dictionary representation of the component.

        :returns:
            Serialized dictionary representation of the component.
        """
        template: list[dict[str, Any]] | str | None = None
        if isinstance(self.template, list):
            template = [m.to_dict() for m in self.template]
        elif isinstance(self.template, str):
            template = self.template

        return default_to_dict(

View on GitHub (pinned to e318778c9b)

Solutions

1. Pass the missing variables as kwargs to run(), matching the names in the error message.
2. Remove the unused placeholder from the template if it is no longer needed.
3. Ensure the pipeline wires the missing variable input correctly.

Example fix

// before
builder.run(query=q)  # missing 'context'
// after
builder.run(query=q, context=retrieved_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 ChatPromptBuilder' in str(e):
        kwargs.update(fill_defaults_from_template(builder))
        res = builder.run(**kwargs)
    else:
        raise

When it happens

Trigger: run(query=q) when the builder's template declares additional variables (e.g. {{ context }}) that are not passed as kwargs nor present in template_variables.

Common situations: Changing a template to add a new placeholder without adding it to the run() call; pipeline connections failing to supply an expected input; required_variables listing a variable you forgot to bind.

Related errors

• ChatMessages from {role} role must contain text. Received Ch
• The templatize_part filter cannot be used with a template co
• The {self.__class__.__name__} requires a non-empty list of C
• The {self.__class__.__name__} expects a list containing only
• Missing required input variables in PromptBuilder: {missing_

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