langchain-ai/langchain · error · ValueError

Arg {docstring_arg} in docstring not found in function signa

Error message

Arg {docstring_arg} in docstring not found in function signature.

What it means

When `@tool` is created with `parse_docstring=True` (Google-style Args: parsing), langchain validates that every argument documented in the docstring exists in the function signature. A documented arg with no matching parameter raises this ValueError at tool-creation time, catching stale docstrings before they produce a broken JSON schema.

Source

Thrown at libs/core/langchain_core/tools/base.py:168

    )


def _validate_docstring_args_against_annotations(
    arg_descriptions: dict[str, str], annotations: dict[str, Any]
) -> None:
    """Validate that docstring arguments match function annotations.

    Args:
        arg_descriptions: Arguments described in the docstring.
        annotations: Type annotations from the function signature.

    Raises:
        ValueError: If a docstring argument is not found in function signature.
    """
    for docstring_arg in arg_descriptions:
        if docstring_arg not in annotations:
            msg = f"Arg {docstring_arg} in docstring not found in function signature."
            raise ValueError(msg)


def _infer_arg_descriptions(
    fn: Callable[..., Any],
    *,
    parse_docstring: bool = False,
    error_on_invalid_docstring: bool = False,
) -> tuple[str, dict[str, str]]:
    """Infer argument descriptions from function docstring and annotations.

    Args:
        fn: The function to infer descriptions from.
        parse_docstring: Whether to parse the docstring for descriptions.
        error_on_invalid_docstring: Whether to raise error on invalid docstring.

    Returns:
        A tuple containing the function description and argument descriptions.
    """

View on GitHub (pinned to e32fa9a52e)

Solutions

Make the docstring `Args:` entries exactly match the function parameter names (spelling and order of names).
Rename the docstring arg or the function parameter so both sides agree.
If the docstring is wrong and you cannot fix it now, drop `parse_docstring=True` and pass `description`/`args_schema` explicitly instead.

Example fix

# before
@tool(parse_docstring=True)
def search(q: str) -> str:
    """Search.

    Args:
        query: the query  # no param named 'query'
    """
# after
@tool(parse_docstring=True)
def search(q: str) -> str:
    """Search.

    Args:
        q: the query
    """

Defensive patterns

Strategy: validation

Validate before calling

import inspect

def docstring_args_match(fn) -> bool:
    import re
    doc = fn.__doc__ or ''
    m = re.search(r'Args:\s*(.*?)(?:\n\n|Returns:|$)', doc, re.S)
    if not m:
        return True
    documented = {line.split(':')[0].strip() for line in m.group(1).splitlines() if ':' in line}
    signature = set(inspect.signature(fn).parameters)
    return documented <= signature

assert docstring_args_match(fn)

Try / catch

try:
    tool = tool_decorator(parse_docstring=True)(fn)
except ValueError as e:
    if 'not found in function signature' in str(e):
        tool = tool_decorator(parse_docstring=False)(fn)  # fix docstring later
    else:
        raise

Prevention

Keep Args: entries exactly in sync with parameter names.
Add a CI lint that compares docstring args to inspect.signature.
Rename parameters and docstring entries together in one commit.

When it happens

Trigger: `@tool(parse_docstring=True)` on a function whose `Args:` section lists a parameter that was renamed or removed (docstring says `query: ...` but the function takes `q`); typos in the Args section; documented kwargs that are not explicit parameters.

Common situations: Renaming a tool function's parameter without updating its Google-style docstring; copying a docstring template between tools; enabling `parse_docstring=True` on legacy tools whose docstrings were never validated.

Related errors

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