{"record":{"id":"5575cce7153290a2","repo":"langchain-ai/langchain","slug":"unrecognized-text-format-expected-one-of-stri","errorCode":null,"errorMessage":"Unrecognized {text_format=}, expected one of 'string' or 'block'.","messagePattern":"Unrecognized (.+?), expected one of 'string' or 'block'\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/messages/utils.py","lineNumber":1642,"sourceCode":"            ToolMessage(\"foobar\", tool_call_id=\"1\", name=\"bar\"),\n            {\"role\": \"assistant\", \"content\": \"that's nice\"},\n        ]\n        oai_messages = convert_to_openai_messages(messages)\n        # -> [\n        #   {'role': 'system', 'content': 'foo'},\n        #   {'role': 'user', 'content': [{'type': 'text', 'text': 'what's in this'}, {'type': 'image_url', 'image_url': {'url': \"data:image/png;base64,'/9j/4AAQSk'\"}}]},\n        #   {'role': 'assistant', 'tool_calls': [{'type': 'function', 'id': '1','function': {'name': 'analyze', 'arguments': '{\"baz\": \"buz\"}'}}], 'content': ''},\n        #   {'role': 'tool', 'name': 'bar', 'content': 'foobar'},\n        #   {'role': 'assistant', 'content': 'that's nice'}\n        # ]\n        ```\n\n    !!! version-added \"Added in `langchain-core` 0.3.11\"\n\n    \"\"\"  # noqa: E501\n    if text_format not in {\"string\", \"block\"}:\n        err = f\"Unrecognized {text_format=}, expected one of 'string' or 'block'.\"\n        raise ValueError(err)\n\n    oai_messages: list[dict[str, Any]] = []\n\n    messages_: Sequence[MessageLikeRepresentation]\n    if is_single := isinstance(messages, (BaseMessage, dict, str)):\n        messages_ = [messages]\n    else:\n        messages_ = cast(\"Sequence[MessageLikeRepresentation]\", messages)\n\n    for i, message in enumerate(convert_to_messages(messages_)):\n        oai_msg: dict[str, Any] = {\"role\": _get_message_openai_role(message)}\n        tool_messages: list[dict[str, Any]] = []\n        content: str | list[dict[str, Any]]\n\n        if message.name:\n            oai_msg[\"name\"] = message.name\n        if isinstance(message, AIMessage) and message.tool_calls:\n            oai_msg[\"tool_calls\"] = _convert_to_openai_tool_calls(message.tool_calls)","sourceCodeStart":1624,"sourceCodeEnd":1660,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/messages/utils.py#L1624-L1660","documentation":"Raised by `convert_to_openai_messages` when `text_format` is not 'string' or 'block'. The parameter controls whether textual content is emitted as a plain string or as `{'type': 'text', 'text': ...}` content blocks; anything else is rejected before conversion starts.","triggerScenarios":"Calling `convert_to_openai_messages(msgs, text_format='plain')` or `text_format='markdown'`.","commonSituations":"Guessing parameter values from intuition instead of the signature; passing a variable defaulting to None; values copied from another library's API.","solutions":["Use `text_format='string'` for plain-string content or `text_format='block'` for OpenAI content-block form","Omit the parameter to keep the default rather than passing an explicit invalid value"],"exampleFix":"# before\nconvert_to_openai_messages(msgs, text_format='plain')\n\n# after\nconvert_to_openai_messages(msgs, text_format='string')","handlingStrategy":"validation","validationCode":"def valid_text_format(f: str) -> bool:\n    return f in {'string', 'block'}\n\nif not valid_text_format(text_format):\n    text_format = 'string'","typeGuard":"def is_text_format(f: object) -> bool:\n    return isinstance(f, str) and f in {'string', 'block'}","tryCatchPattern":null,"preventionTips":["Treat text_format as Literal['string', 'block'] in your wrappers","Omit the kwarg unless you specifically need block-form content"],"tags":["openai","message-conversion","argument-validation"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}