langchain-ai/langchain · error · ValueError

Invalid annotation for field {arg}. Third argument to Annota

Error message

Invalid annotation for field {arg}. Third argument to Annotated must be a string description, received value of type {type(field_desc)}.

What it means

Error "Invalid annotation for field {arg}. Third argument to Annotated must be a string description, received value of type {type(field_desc)}." thrown in langchain-ai/langchain.

Source

Thrown at libs/core/langchain_core/utils/function_calling.py:298

        fields: dict[str, Any] = {}
        for arg, arg_type in annotations_.items():
            if get_origin(arg_type) in {Annotated, typing_extensions.Annotated}:
                annotated_args = get_args(arg_type)
                new_arg_type = _convert_any_typed_dicts_to_pydantic(
                    annotated_args[0], depth=depth + 1, visited=visited
                )
                field_kwargs = dict(
                    zip(("default", "description"), annotated_args[1:], strict=False)
                )
                if (field_desc := field_kwargs.get("description")) and not isinstance(
                    field_desc, str
                ):
                    msg = (
                        f"Invalid annotation for field {arg}. Third argument to "
                        f"Annotated must be a string description, received value of "
                        f"type {type(field_desc)}."
                    )
                    raise ValueError(msg)
                if arg_desc := arg_descriptions.get(arg):
                    field_kwargs["description"] = arg_desc
                fields[arg] = (new_arg_type, Field_v1(**field_kwargs))
            else:
                new_arg_type = _convert_any_typed_dicts_to_pydantic(
                    arg_type, depth=depth + 1, visited=visited
                )
                field_kwargs = {"default": ...}
                if arg_desc := arg_descriptions.get(arg):
                    field_kwargs["description"] = arg_desc
                fields[arg] = (new_arg_type, Field_v1(**field_kwargs))
        model = cast(
            "type[BaseModelV1]", create_model_v1(typed_dict.__name__, **fields)
        )
        model.__doc__ = description
        visited[typed_dict] = model
        return model
    if (origin := get_origin(type_)) and (type_args := get_args(type_)):

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Use Annotated with a string as the third element: Annotated[T, FieldInfo, "description"].
2. If you need structured metadata, use pydantic Field(description=...) instead of passing a non-string in Annotated.

Example fix

def f(arg: Annotated[str, Field(...), "the query"]) -> None: ...

When it happens

Trigger: Raised when an Annotated[..., X] argument annotation is used in a tool function where X (the third element) is not a string description, e.g. a number or another type object.

Common situations: See trigger scenarios.

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