{"record":{"id":"3dbb326ebc64f315","repo":"deepset-ai/haystack","slug":"user-prompt-message-block-must-have-role-user-f","errorCode":null,"errorMessage":"user_prompt message block must have role 'user', found role '{roles[0]}'.","messagePattern":"user_prompt message block must have role 'user', found role '(.+?)'\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/components/agents/utils.py","lineNumber":257,"sourceCode":"# Regex to extract the role from a Jinja2 message block, e.g. {% message role=\"user\" %}\n_JINJA2_MESSAGE_ROLE_RE = re.compile(r'\\{%\\s*message\\s+role\\s*=\\s*[\"\\'](\\w+)[\"\\']')\n\n\ndef _validate_prompt_message_blocks(user_prompt: str | None, system_prompt: str | None) -> None:\n    \"\"\"\n    Validate explicit Jinja2 message blocks in Agent prompts.\n\n    :param user_prompt: Optional user prompt template.\n    :param system_prompt: Optional system prompt template.\n    :raises ValueError: If a prompt contains multiple message blocks or a literal block role is invalid.\n    \"\"\"\n    if user_prompt is not None:\n        message_blocks = _JINJA2_CHAT_TEMPLATE_RE.findall(user_prompt)\n        roles = _JINJA2_MESSAGE_ROLE_RE.findall(user_prompt)\n        if len(message_blocks) > 1:\n            raise ValueError(f\"user_prompt must define exactly one message block, found {len(message_blocks)}.\")\n        if roles and roles[0] != \"user\":\n            raise ValueError(f\"user_prompt message block must have role 'user', found role '{roles[0]}'.\")\n\n    if system_prompt is not None and _JINJA2_CHAT_TEMPLATE_RE.search(system_prompt):\n        message_blocks = _JINJA2_CHAT_TEMPLATE_RE.findall(system_prompt)\n        roles = _JINJA2_MESSAGE_ROLE_RE.findall(system_prompt)\n        if len(message_blocks) > 1:\n            raise ValueError(f\"system_prompt must define exactly one message block, found {len(message_blocks)}.\")\n        if roles and roles[0] != \"system\":\n            raise ValueError(f\"system_prompt message block must have role 'system', found role '{roles[0]}'.\")\n\n\ndef _template_for_role(prompt: str, role: str) -> str:\n    \"\"\"\n    Convert a prompt into a ChatPromptBuilder string template for the expected role.\n\n    :param prompt: Prompt template, with or without an explicit Jinja2 message block.\n    :param role: Role to use when wrapping a plain string prompt.\n    :returns: The original message-block template, or a plain string prompt wrapped in one message block.\n    \"\"\"","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/agents/utils.py#L239-L275","documentation":"Raised when the first Jinja2 message block in user_prompt has a role other than 'user'. The Agent pipeline routes user_prompt through a builder expecting a user-role message, so any other role is rejected at init time.","triggerScenarios":"Passing user_prompt like \"{% message role='system' %}...{% endmessage %}\" or role='assistant' to Agent's __init__.","commonSituations":"Copy-pasting a system message template into user_prompt; swapping user_prompt and system_prompt arguments; editing roles in a template without checking where it is used.","solutions":["Change the message block role in user_prompt to 'user'.","Move system-role content into system_prompt instead.","Verify the user_prompt/system_prompt arguments were not swapped."],"exampleFix":"// before\nuser_prompt = \"{% message role='system' %}You are helpful.{% endmessage %}\"\n// after\nsystem_prompt = \"{% message role='system' %}You are helpful.{% endmessage %}\"\nuser_prompt = \"{% message role='user' %}{{ query }}{% endmessage %}\"","handlingStrategy":"validation","validationCode":"roles = re.findall(r\"{\\%\\s*message\\s+role=['\\\"](\\w+)['\\\"]\", user_prompt)\nassert not roles or roles[0] == \"user\", f\"user_prompt role is {roles[0] if roles else None}\"","typeGuard":null,"tryCatchPattern":"try:\n    agent = Agent(gen, user_prompt=prompt)\nexcept ValueError as e:\n    if \"role 'user'\" in str(e):\n        logging.error(\"user_prompt wrong role: %s\", e)\n    raise","preventionTips":["Hardcode role='user' inside user_prompt templates.","Do not reuse system templates as user_prompt.","Check argument order when constructing Agent."],"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"}