{"record":{"id":"cd7ddc405928bb18","repo":"deepset-ai/haystack","slug":"system-prompt-message-block-must-have-role-system","errorCode":null,"errorMessage":"system_prompt message block must have role 'system', found role '{roles[0]}'.","messagePattern":"system_prompt message block must have role 'system', found role '(.+?)'\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/components/agents/utils.py","lineNumber":265,"sourceCode":"    :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    \"\"\"\n    if _JINJA2_CHAT_TEMPLATE_RE.search(prompt):\n        return prompt\n    return f'{{% message role=\"{role}\" %}}{prompt}{{% endmessage %}}'\n\n\ndef _render_prompt_messages(\n    *, prompt_builder: ChatPromptBuilder, expected_role: ChatRole, prompt_label: str, kwargs: dict[str, Any]\n) -> list[ChatMessage]:","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/agents/utils.py#L247-L283","documentation":"Raised when the first (only) message block in system_prompt has a role other than 'system'. The Agent expects the system prompt to render to a system-role ChatMessage.","triggerScenarios":"Passing system_prompt like \"{% message role='user' %}...{% endmessage %}\" to Agent's __init__.","commonSituations":"Swapping user_prompt and system_prompt arguments; using an instruction template with role='user' as the system prompt.","solutions":["Change the message block role in system_prompt to 'system'.","Move user-role content into user_prompt.","Double-check argument order when constructing Agent to avoid swapping the two prompts."],"exampleFix":"// before\nsystem_prompt = \"{% message role='user' %}{{ query }}{% endmessage %}\"\n// after\nsystem_prompt = \"{% message role='system' %}You are a helpful assistant.{% endmessage %}\"","handlingStrategy":"validation","validationCode":"roles = re.findall(r\"{\\%\\s*message\\s+role=['\\\"](\\w+)['\\\"]\", system_prompt)\nassert not roles or roles[0] == \"system\", f\"system_prompt role is {roles[0] if roles else None}\"","typeGuard":null,"tryCatchPattern":"try:\n    agent = Agent(gen, system_prompt=prompt)\nexcept ValueError as e:\n    if \"role 'system'\" in str(e):\n        logging.error(\"system_prompt wrong role: %s\", e)\n    raise","preventionTips":["Hardcode role='system' inside system_prompt templates.","Do not pass user-turn templates as system_prompt.","Verify prompts after refactoring template variables."],"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"}