{"record":{"id":"8343570fbba5215c","repo":"deepset-ai/haystack","slug":"prompt-label-must-render-to-a-expected-role-val","errorCode":null,"errorMessage":"{prompt_label} must render to a {expected_role.value} message. Got a message with role {prompt_messages[0].role}.","messagePattern":"(.+?) must render to a (.+?) message\\. Got a message with role (.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/components/agents/utils.py","lineNumber":302,"sourceCode":"    \"\"\"\n    Render one Agent prompt and validate the rendered message.\n\n    :param prompt_builder: Builder configured with the prompt template.\n    :param expected_role: Role the rendered message must have.\n    :param prompt_label: Prompt name used in error messages.\n    :param kwargs: Runtime values available to the prompt template.\n    :returns: A single rendered prompt message.\n    :raises ValueError: If the prompt renders to zero, multiple, or wrong-role messages.\n    \"\"\"\n    prompt_kwargs = {var: kwargs[var] for var in prompt_builder.variables if var in kwargs}\n    prompt_messages = prompt_builder.run(**prompt_kwargs)[\"prompt\"]\n    if len(prompt_messages) != 1:\n        raise ValueError(\n            f\"{prompt_label} must render to exactly one {expected_role.value} message. \"\n            f\"Got {len(prompt_messages)} messages.\"\n        )\n    if not prompt_messages[0].is_from(expected_role):\n        raise ValueError(\n            f\"{prompt_label} must render to a {expected_role.value} message. \"\n            f\"Got a message with role {prompt_messages[0].role}.\"\n        )\n    return prompt_messages\n","sourceCodeStart":284,"sourceCodeEnd":307,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/agents/utils.py#L284-L307","documentation":"Raised when the prompt renders to exactly one message, but that message's role does not match the expected role for the prompt label (user or system). Caught at execution setup, after init-time static validation passed because the role was decided by template variables at render time.","triggerScenarios":"A template with a dynamic role (e.g. {% message role=role_var %}) where the runtime variable resolves to the wrong role for the prompt.","commonSituations":"Passing a role variable via run kwargs that overrides the expected role; mutating prompt template variables between init and run so the rendered role changes.","solutions":["Fix the template so the rendered message role is hardcoded or constrained to the expected role ('user' for user_prompt, 'system' for system_prompt).","Remove or correct any role variable passed via template kwargs.","Add an explicit condition in the template raising for unexpected role values before rendering."],"exampleFix":"// before\nprompt = \"{% message role=role %}{{ query }}{% endmessage %}\"; agent.run(..., role=\"system\")\n// after\nprompt = \"{% message role='user' %}{{ query }}{% endmessage %}\"","handlingStrategy":"validation","validationCode":"out = prompt_builder.run(**kwargs)[\"prompt\"]\nassert len(out) == 1 and out[0].is_from(expected_role), f\"got role {out[0].role if out else None}\"","typeGuard":null,"tryCatchPattern":"try:\n    agent.run(**kwargs)\nexcept ValueError as e:\n    if \"Got a message with role\" in str(e):\n        logging.error(\"Rendered prompt wrong role: %s\", e)\n    raise","preventionTips":["Hardcode roles in message templates; do not pass role as a variable.","Guard template variables that could change the role.","Assert rendered role in pipeline tests."],"tags":["haystack","agents","prompt","role-mismatch"],"backgroundTag":"wrong-message-role","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}