{"record":{"id":"4f8d896fbc375525","repo":"deepset-ai/haystack","slug":"role-must-be-one-of-join-self-supported-rol","errorCode":null,"errorMessage":"Role must be one of: {', '.join(self.SUPPORTED_ROLES)}","messagePattern":"Role must be one of: (.+?)","errorType":"validation","errorClass":"TemplateSyntaxError","httpStatus":null,"severity":"error","filePath":"haystack/utils/jinja2_chat_extension.py","lineNumber":189,"sourceCode":"        Parse the message tag and its attributes in the Jinja2 template.\n\n        This method handles the parsing of role (mandatory), name (optional), meta (optional) and message body content.\n\n        :param parser: The Jinja2 parser instance\n        :param lineno: The line number of the tag, used for error reporting.\n        :return: A CallBlock node containing the parsed message configuration\n        :raises TemplateSyntaxError: If an invalid role is provided\n        \"\"\"\n\n        # Parse role attribute (mandatory)\n        parser.stream.expect(\"name:role\")\n        parser.stream.expect(\"assign\")\n        role_expr = parser.parse_expression()\n\n        if isinstance(role_expr, nodes.Const):\n            role = role_expr.value\n            if role not in self.SUPPORTED_ROLES:\n                raise TemplateSyntaxError(f\"Role must be one of: {', '.join(self.SUPPORTED_ROLES)}\", lineno)\n\n        # Parse optional name attribute\n        name_expr = None\n        if parser.stream.current.test(\"name:name\"):\n            parser.stream.skip()\n            parser.stream.expect(\"assign\")\n            name_expr = parser.parse_expression()\n            if not isinstance(name_expr.value, str):\n                raise TemplateSyntaxError(\"name must be a string\", lineno)\n\n        # Parse optional meta attribute\n        meta_expr = None\n        if parser.stream.current.test(\"name:meta\"):\n            parser.stream.skip()\n            parser.stream.expect(\"assign\")\n            meta_expr = parser.parse_expression()\n            if not isinstance(meta_expr, nodes.Dict):\n                raise TemplateSyntaxError(\"meta must be a dictionary\", lineno)","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/utils/jinja2_chat_extension.py#L171-L207","documentation":"TemplateSyntaxError raised by `_parse_message_tag` when the role assigned to a {% message %} tag is a literal constant that is not in SUPPORTED_ROLES. Only a fixed set of chat roles (e.g. user, assistant, system, tool) are allowed for message templates.","triggerScenarios":"Writing `{% message role='bot' %}` or `{% message role='Agent' %}` (wrong casing) or any other literal role not in SUPPORTED_ROLES in a chat template parsed by this Jinja2 extension.","commonSituations":"Using role names from other frameworks (OpenAI 'function', 'developer'); capitalized roles; typos like 'asistant'; hardcoding roles instead of relying on the default.","solutions":["Use a supported role literal, e.g. {% message role='user' %} or role='assistant'","Inspect the extension's SUPPORTED_ROLES to see the exact allowed values","Remove the role attribute to use the default if a custom role is unnecessary"],"exampleFix":"// before\n{% message role='bot' %}Hi{% endmessage %}\n// after\n{% message role='assistant' %}Hi{% endmessage %}","handlingStrategy":"validation","validationCode":"SUPPORTED_ROLES = {\"user\", \"assistant\", \"system\", \"tool\"}  # check the extension for exact set\nassert role.lower() in SUPPORTED_ROLES, f\"role must be one of {SUPPORTED_ROLES}\"","typeGuard":"null","tryCatchPattern":"from jinja2.exceptions import TemplateSyntaxError\ntry:\n    env.parse(template)\nexcept TemplateSyntaxError as e:\n    raise ValueError(f\"Invalid role in template: {e.message}\") from e","preventionTips":["Use lowercase role literals from SUPPORTED_ROLES only","Don't invent roles from other providers (e.g. 'developer', 'function')","Parse templates at load time to catch invalid roles early"],"tags":["haystack","jinja2","template-syntax-error","message-tag","invalid-role"],"backgroundTag":"invalid-enum-value","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}