deepset-ai/haystack · error · ValueError

The {self.__class__.__name__} requires a non-empty list of C

Error message

The {self.__class__.__name__} requires a non-empty list of ChatMessage instances. Please provide a valid list of ChatMessage instances to render the prompt.

What it means

ChatPromptBuilder.run (via _render_prompt_messages) raises when the effective template is falsy — i.e. neither run's template argument nor self.template contains a non-empty list of ChatMessages. Without a template there is nothing to render, so the call is invalid.

Source

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

        :param template_variables:
            An optional dictionary of template variables to overwrite the pipeline variables.
        :param kwargs:
            Pipeline variables used for rendering the prompt.

        :returns: A dictionary with the following keys:
            - `prompt`: The updated list of `ChatMessage` objects after rendering the templates.
        :raises ValueError:
            If `chat_messages` is empty or contains elements that are not instances of `ChatMessage`.
        """
        kwargs = kwargs or {}
        template_variables = template_variables or {}
        template_variables_combined = {**kwargs, **template_variables}

        if template is None:
            template = self.template

        if not template:
            raise ValueError(
                f"The {self.__class__.__name__} requires a non-empty list of ChatMessage instances. "
                f"Please provide a valid list of ChatMessage instances to render the prompt."
            )

        if isinstance(template, list) and not all(isinstance(message, ChatMessage) for message in template):
            raise ValueError(
                f"The {self.__class__.__name__} expects a list containing only ChatMessage instances. "
                f"The provided list contains other types. Please ensure that all elements in the list "
                f"are ChatMessage instances."
            )

        processed_messages = []
        if isinstance(template, list):
            for message in template:
                if message.is_from(ChatRole.USER) or message.is_from(ChatRole.SYSTEM):
                    self._validate_variables(set(template_variables_combined.keys()))
                    if message.text is None:
                        raise ValueError(NO_TEXT_ERROR_MESSAGE.format(role=message.role.value, message=message))

View on GitHub (pinned to e318778c9b)

Solutions

1. Pass a non-empty list of ChatMessage objects to run(template=[...]).
2. Provide the template at construction: ChatPromptBuilder(template=[...]).
3. Check that a pipeline connection feeding the template input is actually bound and non-empty.

Example fix

// before
builder = ChatPromptBuilder(template=None, required_variables=['q'])
result = builder.run()  # no template anywhere
// after
result = builder.run(template=[ChatMessage.from_user('Question: {{ q }}')], q=q)

if not template:
    raise ValueError('template must be a non-empty list of ChatMessage before calling run')

def is_valid_template(t) -> bool:
    return bool(t) and isinstance(t, list)

try:
    res = builder.run(template=template, **kwargs)
except ValueError as e:
    if 'requires a non-empty list' in str(e):
        template = default_template
        res = builder.run(template=template, **kwargs)
    else:
        raise

When it happens

Trigger: Calling run() without a template argument on a builder constructed with template=None (e.g. created with template=None and required_variables, expecting template at run time) or passing template=[].

Common situations: Wiring ChatPromptBuilder in a pipeline with dynamic templates but forgetting to connect the template input; instantiating with template=None and never passing it in run; passing an empty list after filtering messages.

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__} expects a list containing only
• Missing required input variables in ChatPromptBuilder: {miss
• No inputs provided.

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