{"record":{"id":"0919024d78e1fcf1","repo":"langchain-ai/langchain","slug":"exactly-one-argument-in-each-of-the-following-grou","errorCode":null,"errorMessage":"Exactly one argument in each of the following groups must be defined: {', '.join(invalid_group_names)}","messagePattern":"Exactly one argument in each of the following groups must be defined: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/utils/utils.py","lineNumber":50,"sourceCode":"    \"\"\"\n\n    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:\n        @functools.wraps(func)\n        def wrapper(*args: Any, **kwargs: Any) -> Any:\n            \"\"\"Validate exactly one arg in each group is not None.\"\"\"\n            counts = [\n                sum(1 for arg in arg_group if kwargs.get(arg) is not None)\n                for arg_group in arg_groups\n            ]\n            invalid_groups = [i for i, count in enumerate(counts) if count != 1]\n            if invalid_groups:\n                invalid_group_names = [\", \".join(arg_groups[i]) for i in invalid_groups]\n                msg = (\n                    \"Exactly one argument in each of the following\"\n                    \" groups must be defined:\"\n                    f\" {', '.join(invalid_group_names)}\"\n                )\n                raise ValueError(msg)\n            return func(*args, **kwargs)\n\n        return wrapper\n\n    return decorator\n\n\ndef raise_for_status_with_text(response: Response) -> None:\n    \"\"\"Raise an error with the response text.\n\n    Args:\n        response: The response to check for errors.\n\n    Raises:\n        ValueError: If the response has an error status code.\n    \"\"\"\n    try:\n        response.raise_for_status()","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/utils/utils.py#L32-L68","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nresult = decorated_func(prompt=p, messages=[m])  # two set -> ValueError\n# or\nresult = decorated_func()  # zero set -> ValueError\n\n# after\nresult = decorated_func(messages=[m])\n# or\nresult = decorated_func(prompt=p)","handlingStrategy":"validation","validationCode":"def check_xor(groups: dict[str, tuple[str, ...]], kwargs: dict) -> None:\n    for label, group in groups.items():\n        n = sum(kwargs.get(a) is not None for a in group)\n        if n != 1:\n            raise ValueError(f\"group '{label}' ({', '.join(group)}): exactly one must be set, got {n}\")\n\ncheck_xor({\"input\": (\"messages\", \"prompt\")}, {\"messages\": msgs, \"prompt\": None})","typeGuard":null,"tryCatchPattern":"try:\n    result = api_call(**kwargs)\nexcept ValueError as e:\n    if \"Exactly one argument\" in str(e):\n        raise TypeError(f\"bad kwargs for {api_call.__name__}: {e}\") from e\n    raise","preventionTips":["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."],"tags":["api-contract","arguments","validation"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}