{"record":{"id":"58dd9031d8663970","repo":"langchain-ai/langchain","slug":"unexpected-arguments-for-placeholder-message-type","errorCode":null,"errorMessage":"Unexpected arguments for placeholder message type. Expected either a single string variable name or a list of [variable_name: str, is_optional: bool]. Got: {template}","messagePattern":"Unexpected arguments for placeholder message type\\. Expected either a single string variable name or a list of \\[variable_name: str, is_optional: bool\\]\\. Got: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/prompts/chat.py","lineNumber":1391,"sourceCode":"            if template[0] != \"{\" or template[-1] != \"}\":\n                msg = (\n                    f\"Invalid placeholder template: {template}.\"\n                    \" Expected a variable name surrounded by curly braces.\"\n                )\n                raise ValueError(msg)\n            var_name = template[1:-1]\n            message = MessagesPlaceholder(variable_name=var_name, optional=True)\n        else:\n            try:\n                var_name_wrapped, is_optional = template\n            except ValueError as e:\n                msg = (\n                    \"Unexpected arguments for placeholder message type.\"\n                    \" Expected either a single string variable name\"\n                    \" or a list of [variable_name: str, is_optional: bool].\"\n                    f\" Got: {template}\"\n                )\n                raise ValueError(msg) from e\n\n            if not isinstance(is_optional, bool):\n                msg = f\"Expected is_optional to be a boolean. Got: {is_optional}\"\n                raise ValueError(msg)  # noqa: TRY004\n\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:","sourceCodeStart":1373,"sourceCodeEnd":1409,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/prompts/chat.py#L1373-L1409","documentation":"Raised in _create_template_from_message_type when a \"placeholder\" message's template value is neither a string nor a 2-element sequence [variable_name, is_optional]. The code tries to unpack the value into (var_name_wrapped, is_optional) and a ValueError from unpacking means the shape is wrong — e.g. a 3-element list or an empty one.","triggerScenarios":"`ChatPromptTemplate.from_messages([(\"placeholder\", [\"{history}\", True, \"extra\"])])` (3 items), or (\"placeholder\", [\"{history}\"]) (1 item), or (\"placeholder\", 123) (non-iterable).","commonSituations":"Attempting to pass extra options to the placeholder (like optional plus a default), or passing the variable name wrapped in a list of wrong length when migrating from older tuple APIs.","solutions":["Use exactly two elements: (\"placeholder\", [\"{variable_name}\", is_optional_bool]).","For a required placeholder, use the string form (\"placeholder\", \"{variable_name}\") which defaults optional=True only via structured form — note the string form creates optional=True; use the list form with False for required.","Remove any extra list elements beyond [name, bool]."],"exampleFix":"# before\nChatPromptTemplate.from_messages([(\"placeholder\", [\"{history}\", True, 0])])\n\n# after\nChatPromptTemplate.from_messages([(\"placeholder\", [\"{history}\", True])])","handlingStrategy":"validation","validationCode":"def valid_placeholder_spec(t):\n    if isinstance(t, str):\n        return True\n    return isinstance(t, (list, tuple)) and len(t) == 2","typeGuard":"def is_placeholder_spec(t) -> bool:\n    return isinstance(t, str) or (isinstance(t, (list, tuple)) and len(t) == 2)","tryCatchPattern":null,"preventionTips":["Keep placeholder specs to exactly [\"{name}\", bool].","Validate externally sourced message specs before from_messages."],"tags":["prompts","messages-placeholder","from-messages"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}