{"record":{"id":"2005e2ee95a2a0a6","repo":"langchain-ai/langchain","slug":"unexpected-message-type-message-type-use-one-o","errorCode":null,"errorMessage":"Unexpected message type: {message_type}. Use one of 'human', 'user', 'ai', 'assistant', or 'system'.","messagePattern":"Unexpected message type: (.+?)\\. Use one of 'human', 'user', 'ai', 'assistant', or 'system'\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/prompts/chat.py","lineNumber":1414,"sourceCode":"\n            if not isinstance(var_name_wrapped, str):\n                msg = f\"Expected variable name to be a string. Got: {var_name_wrapped}\"\n                raise ValueError(msg)  # noqa: TRY004\n            if var_name_wrapped[0] != \"{\" or var_name_wrapped[-1] != \"}\":\n                msg = (\n                    f\"Invalid placeholder template: {var_name_wrapped}.\"\n                    \" Expected a variable name surrounded by curly braces.\"\n                )\n                raise ValueError(msg)\n            var_name = var_name_wrapped[1:-1]\n\n            message = MessagesPlaceholder(variable_name=var_name, optional=is_optional)\n    else:\n        msg = (\n            f\"Unexpected message type: {message_type}. Use one of 'human',\"\n            f\" 'user', 'ai', 'assistant', or 'system'.\"\n        )\n        raise ValueError(msg)\n    return message\n\n\ndef _convert_to_message_template(\n    message: MessageLikeRepresentation,\n    template_format: PromptTemplateFormat = \"f-string\",\n) -> BaseMessage | BaseMessagePromptTemplate | BaseChatPromptTemplate:\n    \"\"\"Instantiate a message from a variety of message formats.\n\n    A message can be represented using the following formats:\n\n    1. `BaseMessagePromptTemplate`\n    2. `BaseMessage`\n    3. 2-tuple of `(message type, template)`; e.g., `('human', '{user_input}')`\n    4. 2-tuple of `(message class, template)`\n    5. A string which is shorthand for `('human', template)`; e.g., `'{user_input}'`\n\n    Args:","sourceCodeStart":1396,"sourceCodeEnd":1432,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/prompts/chat.py#L1396-L1432","documentation":"Raised in _create_template_from_message_type when the message role string is not one of the recognized types: 'human'/'user', 'ai'/'assistant', 'system', or 'placeholder'. The role comes from the first element of a (role, template) tuple or the 'role' key of a dict message.","triggerScenarios":"`ChatPromptTemplate.from_messages([(\"bot\", \"hi\")])`, `[{\"role\": \"tool\", \"content\": ...}]`, or a typo like \"System\" (capitalized) or \"aı\" — none are mapped. Note 'tool' and 'placeholder' handling differs: only the listed roles are accepted here.","commonSituations":"Porting OpenAI-style message lists (which allow 'tool' and 'function' roles) into from_messages; typos and case mismatches; role strings sourced from user input or a database.","solutions":["Map the role to an accepted one: 'bot'->'ai', 'user'->'human', 'assistant'->'ai'.","For tool/function messages, pass the actual message class (ToolMessage(...)) instead of a role tuple.","Normalize role strings to lowercase and validate against the accepted set before building the prompt."],"exampleFix":"# before\nChatPromptTemplate.from_messages([(\"bot\", \"hi\")])\n\n# after\nChatPromptTemplate.from_messages([(\"ai\", \"hi\")])","handlingStrategy":"validation","validationCode":"ACCEPTED_ROLES = {\"human\", \"user\", \"ai\", \"assistant\", \"system\", \"placeholder\"}\n\ndef normalize_role(role):\n    r = role.lower()\n    aliases = {\"bot\": \"ai\", \"model\": \"ai\", \"tool\": None}\n    return aliases.get(r, r if r in ACCEPTED_ROLES else None)","typeGuard":"def is_supported_role(role: str) -> bool:\n    return role in {\"human\", \"user\", \"ai\", \"assistant\", \"system\", \"placeholder\"}","tryCatchPattern":"try:\n    prompt = ChatPromptTemplate.from_messages(messages)\nexcept ValueError as e:\n    if \"Unexpected message type\" in str(e):\n        # log offending role and map/fix it\n        raise\n    raise","preventionTips":["Map external role vocabularies (OpenAI, Anthropic, app-specific) to LangChain roles at the boundary.","Lowercase and validate role strings from user/config input before building prompts.","Use typed message objects for roles with no tuple equivalent (tool, function)."],"tags":["prompts","chat-template","from-messages","roles"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}