langchain-ai/langchain · error · ValueError

Exactly one argument in each of the following groups must be

Error message

Exactly one argument in each of the following groups must be defined: {', '.join(invalid_group_names)}

What it means

Raised by the `@xor_args` decorator in `langchain_core.utils.utils` when a decorated function/method is called without exactly one non-`None` keyword argument in every declared group. The message lists the offending argument groups (e.g. `messages, prompt`). Many LangChain classes use this decorator for mutually exclusive parameters, so the error usually comes from an internal LangChain call site after you passed the wrong combination of kwargs.

Source

Thrown at libs/core/langchain_core/utils/utils.py:50

    """

    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        @functools.wraps(func)
        def wrapper(*args: Any, **kwargs: Any) -> Any:
            """Validate exactly one arg in each group is not None."""
            counts = [
                sum(1 for arg in arg_group if kwargs.get(arg) is not None)
                for arg_group in arg_groups
            ]
            invalid_groups = [i for i, count in enumerate(counts) if count != 1]
            if invalid_groups:
                invalid_group_names = [", ".join(arg_groups[i]) for i in invalid_groups]
                msg = (
                    "Exactly one argument in each of the following"
                    " groups must be defined:"
                    f" {', '.join(invalid_group_names)}"
                )
                raise ValueError(msg)
            return func(*args, **kwargs)

        return wrapper

    return decorator


def raise_for_status_with_text(response: Response) -> None:
    """Raise an error with the response text.

    Args:
        response: The response to check for errors.

    Raises:
        ValueError: If the response has an error status code.
    """
    try:
        response.raise_for_status()

View on GitHub (pinned to e32fa9a52e)

Solutions

Read the message: it names the argument group. Supply exactly one non-None value from that group.
If you must pass `None` explicitly for the unused alternative, that is fine — the decorator counts non-None values.
If you are calling with positional arguments against a decorated signature, switch to keyword arguments so the decorator sees them.
Check for default values in your wrapper/config that pre-populate more than one member of the group.

Example fix

# before
result = decorated_func(prompt=p, messages=[m])  # two set -> ValueError
# or
result = decorated_func()  # zero set -> ValueError

# after
result = decorated_func(messages=[m])
# or
result = decorated_func(prompt=p)

Defensive patterns

Strategy: validation

Validate before calling

def check_xor(groups: dict[str, tuple[str, ...]], kwargs: dict) -> None:
    for label, group in groups.items():
        n = sum(kwargs.get(a) is not None for a in group)
        if n != 1:
            raise ValueError(f"group '{label}' ({', '.join(group)}): exactly one must be set, got {n}")

check_xor({"input": ("messages", "prompt")}, {"messages": msgs, "prompt": None})

Try / catch

try:
    result = api_call(**kwargs)
except ValueError as e:
    if "Exactly one argument" in str(e):
        raise TypeError(f"bad kwargs for {api_call.__name__}: {e}") from e
    raise

Prevention

Read the message: it names the exact mutually exclusive group.
Always call decorated APIs with keyword arguments, never positionals.
Avoid wrapper defaults that pre-set more than one member of a group.

When it happens

Trigger: Calling a decorated API with zero or multiple set arguments from a group: e.g. chat-model or agent methods guarded by `@xor_args(("messages", "prompt"))` invoked with both `messages=[...]` and `prompt=...`, or with neither; also passing positional args where the decorator only inspects kwargs, making the count zero even though a value was supplied positionally.

Common situations: Constructing or invoking client objects where docs say 'exactly one of X, Y'; code that defaults two related kwargs to non-None sentinel values; refactors converting positional calls to kwargs or vice versa; conditional code that sometimes sets both flags.

Related errors

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