{"record":{"id":"700cb15db5c45684","repo":"deepset-ai/haystack","slug":"system-prompt-must-define-exactly-one-message-bloc","errorCode":null,"errorMessage":"system_prompt must define exactly one message block, found {len(message_blocks)}.","messagePattern":"system_prompt must define exactly one message block, found (.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/components/agents/utils.py","lineNumber":263,"sourceCode":"    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    \"\"\"\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(","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/agents/utils.py#L245-L281","documentation":"Raised when a system_prompt passed to Agent contains more than one Jinja2 message block. Like user_prompt, the system prompt must render to exactly one message so the Agent can build a valid chat.","triggerScenarios":"Passing a system_prompt with two or more {% message %} blocks, e.g. a template containing both system and user turns.","commonSituations":"Reusing a full chat template as system_prompt; appending extra message blocks for examples; merging two system prompts by concatenation.","solutions":["Reduce system_prompt to a single {% message role='system' %} block.","Put user-turn content in user_prompt instead of system_prompt.","Merge multiple system instructions into one message block separated by newlines."],"exampleFix":"// before\nsystem_prompt = \"{% message role='system' %}A{% endmessage %}{% message role='system' %}B{% endmessage %}\"\n// after\nsystem_prompt = \"{% message role='system' %}A\\nB{% endmessage %}\"","handlingStrategy":"validation","validationCode":"blocks = re.findall(r\"{\\%\\s*message\\s+.*?\\%}.*?{\\%\\s*endmessage\\s*\\%}\", system_prompt, re.DOTALL)\nassert len(blocks) <= 1, f\"system_prompt has {len(blocks)} message blocks\"","typeGuard":null,"tryCatchPattern":"try:\n    agent = Agent(gen, system_prompt=prompt)\nexcept ValueError as e:\n    if \"system_prompt must define exactly one\" in str(e):\n        logging.error(\"system_prompt malformed: %s\", e)\n    raise","preventionTips":["Keep system_prompt to one {% message role='system' %} block.","Concatenate multiple instructions inside a single block.","Never paste multi-turn chat templates into system_prompt."],"tags":["haystack","agents","prompt","validation"],"backgroundTag":"multiple-message-blocks","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}