langchain-ai/langchain · error · ValueError

Unrecognized {text_format=}, expected one of 'string' or 'bl

Error message

Unrecognized {text_format=}, expected one of 'string' or 'block'.

What it means

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.

Source

Thrown at libs/core/langchain_core/messages/utils.py:1642

            ToolMessage("foobar", tool_call_id="1", name="bar"),
            {"role": "assistant", "content": "that's nice"},
        ]
        oai_messages = convert_to_openai_messages(messages)
        # -> [
        #   {'role': 'system', 'content': 'foo'},
        #   {'role': 'user', 'content': [{'type': 'text', 'text': 'what's in this'}, {'type': 'image_url', 'image_url': {'url': "data:image/png;base64,'/9j/4AAQSk'"}}]},
        #   {'role': 'assistant', 'tool_calls': [{'type': 'function', 'id': '1','function': {'name': 'analyze', 'arguments': '{"baz": "buz"}'}}], 'content': ''},
        #   {'role': 'tool', 'name': 'bar', 'content': 'foobar'},
        #   {'role': 'assistant', 'content': 'that's nice'}
        # ]
        ```

    !!! version-added "Added in `langchain-core` 0.3.11"

    """  # noqa: E501
    if text_format not in {"string", "block"}:
        err = f"Unrecognized {text_format=}, expected one of 'string' or 'block'."
        raise ValueError(err)

    oai_messages: list[dict[str, Any]] = []

    messages_: Sequence[MessageLikeRepresentation]
    if is_single := isinstance(messages, (BaseMessage, dict, str)):
        messages_ = [messages]
    else:
        messages_ = cast("Sequence[MessageLikeRepresentation]", messages)

    for i, message in enumerate(convert_to_messages(messages_)):
        oai_msg: dict[str, Any] = {"role": _get_message_openai_role(message)}
        tool_messages: list[dict[str, Any]] = []
        content: str | list[dict[str, Any]]

        if message.name:
            oai_msg["name"] = message.name
        if isinstance(message, AIMessage) and message.tool_calls:
            oai_msg["tool_calls"] = _convert_to_openai_tool_calls(message.tool_calls)

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Use `text_format='string'` for plain-string content or `text_format='block'` for OpenAI content-block form
2. Omit the parameter to keep the default rather than passing an explicit invalid value

Example fix

# before
convert_to_openai_messages(msgs, text_format='plain')

# after
convert_to_openai_messages(msgs, text_format='string')

def valid_text_format(f: str) -> bool:
    return f in {'string', 'block'}

if not valid_text_format(text_format):
    text_format = 'string'

def is_text_format(f: object) -> bool:
    return isinstance(f, str) and f in {'string', 'block'}

When it happens

Trigger: Calling `convert_to_openai_messages(msgs, text_format='plain')` or `text_format='markdown'`.

Common situations: Guessing parameter values from intuition instead of the signature; passing a variable defaulting to None; values copied from another library's API.

Related errors

• mime_type key is required for base64 data.
• Unsupported source type. Only 'url' and 'base64' are support
• OpenAI Chat Completions does not support file URLs.
• Keys base64, url, or file_id required for file blocks.
• Key base64 is required for audio blocks.

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/5575cce7153290a2. Report an issue: GitHub.