deepset-ai/haystack · error · OutputAdaptationException

Undefined variable in the template {self.template}; kwargs:

Error message

Undefined variable in the template {self.template}; kwargs: {kwargs}

What it means

After rendering, if Jinja returns an jinja2.runtime.Undefined object (a template variable was never provided), run() raises OutputAdaptationException naming the template and the kwargs that were actually passed, making the missing-variable mismatch explicit.

Source

Thrown at haystack/components/converters/output_adapter.py:133

        :param kwargs:
            Must contain all variables used in the `template` string.
        :returns:
            A dictionary with the following keys:
            - `output`: Rendered Jinja template.

        :raises OutputAdaptationException: If template rendering fails.
        """
        # check if kwargs are empty
        if not kwargs:
            raise ValueError("No input data provided for output adaptation")
        for name, filter_func in self.custom_filters.items():
            self._env.filters[name] = filter_func
        adapted_outputs = {}
        try:
            adapted_output_template = self._env.from_string(self.template)
            output_result = adapted_output_template.render(**kwargs)
            if isinstance(output_result, jinja2.runtime.Undefined):
                raise OutputAdaptationException(f"Undefined variable in the template {self.template}; kwargs: {kwargs}")  # noqa: TRY301

            # We suppress the exception in case the output is already a string, otherwise
            # we try to evaluate it and would fail.
            # This must be done cause the output could be different literal structures.
            # This doesn't support any user types.
            with contextlib.suppress(Exception):
                if not self._unsafe:
                    output_result = ast.literal_eval(output_result)

            adapted_outputs["output"] = output_result
        except Exception as e:
            raise OutputAdaptationException(f"Error adapting {self.template} with {kwargs}: {e}") from e
        return adapted_outputs

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

View on GitHub (pinned to e318778c9b)

Solutions

Pass the missing variable in run() kwargs
Correct the variable name in the template to match an available kwarg
Add a default in the template: {{ summary | default('') }}

Example fix

// before
adapter.run(docs=docs)  # template uses {{ summary }}
// after
adapter.run(docs=docs, summary=summary)

Defensive patterns

Strategy: validation

Validate before calling

import re
VAR_RE = re.compile(r"{{\s*(\w+)\s*}")
def missing_vars(template: str, kwargs: dict) -> set:
    return {v for v in VAR_RE.findall(template) if v not in kwargs}

Try / catch

try:
    out = adapter.run(**kwargs)
except OutputAdaptationException as e:
    if "Undefined variable" in str(e):
        provide_defaults_and_retry(kwargs)
    else:
        raise

Prevention

Keep template variable names in sync with upstream output keys
Use {{ var | default(...) }} for optional values
Add a pre-run check comparing template variables against kwargs

When it happens

Trigger: Template references a variable not supplied in run() kwargs, and the StrictUndefined/undefined result survives rendering — e.g. run(template uses {{ summary }} but kwargs only contain docs).

Common situations: Renaming an output key upstream without updating the template; typos in variable names; templates copied from another pipeline expecting different inputs.

Related errors

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