From a179d1365ea5ff89ed607e850aeca51726edb063 Mon Sep 17 00:00:00 2001 From: aayushbaluni <73417844+aayushbaluni@users.noreply.github.com> Date: Fri, 16 Oct 2026 13:23:21 +0530 Subject: [PATCH] fix: warn when `user` is dropped instead of silently discarding it A param in PROVIDER_UNVALIDATED_PARAMS that the provider does not support is the one case that is neither sent nor refused: _check_valid_arg skips it before it can reach unsupported_params, so no UnsupportedParamsError is raised, and map_openai_params only copies supported names, so it never reaches the wire either. The caller sees success and a param that did nothing. `user` is only a supported param for models in OpenAI's own catalog, so passing it to a self-hosted OpenAI-compatible model silently drops it and the proxy's per-customer spend attribution records nothing. Warn once per (param, provider, model), capped, and name the x-litellm-end-user-id header as the workaround. Only params with an entry in UNVALIDATED_PARAM_DROP_HINTS warn: stream, stream_options and max_retries are transport controls and would be noise. Fixes #45015 Tests go in tests/unit/test_utils_get_optional_params.py, which is where tests/llm_translation/test_optional_params.py moved to upstream; the earlier version of this branch targeted the old path, which is why it went conflicting. The no-hint test calls warn_unvalidated_param_dropped directly. Routing it through get_optional_params does not reach the guard, because for provider=openai stream/stream_options/max_retries are all supported params and never enter the branch -- so that assertion passed without running the code it named. --- litellm/utils.py | 72 ++++++++++ tests/unit/test_utils_get_optional_params.py | 133 +++++++++++++++++++ 2 files changed, 205 insertions(+) diff --git a/litellm/utils.py b/litellm/utils.py index c0c80f09e4a..d620bb45026 100644 --- a/litellm/utils.py +++ b/litellm/utils.py @@ -4618,6 +4618,15 @@ def get_optional_params( for k in non_default_params: if k not in supported_params: if k in PROVIDER_UNVALIDATED_PARAMS: + # `k` comes from `get_non_default_params`, annotated `-> dict`, + # so its keys are Unknown to the type checker and passing one + # as an argument trips reportUnknownArgumentType. Matching it + # against the hint table's own keys yields the same string + # with a known type, and the table is the set that warns. + for hinted_param in UNVALIDATED_PARAM_DROP_HINTS: + if hinted_param == k: + warn_unvalidated_param_dropped(hinted_param, custom_llm_provider, model) + break continue if k == "n" and n == 1: # langchain sends n=1 as a default value continue # skip this param @@ -5233,6 +5242,69 @@ _apply_openai_param_overrides = apply_openai_param_overrides PROVIDER_UNVALIDATED_PARAMS: Final = frozenset({"user", "stream_options", "stream", "max_retries"}) +# A param in PROVIDER_UNVALIDATED_PARAMS that the provider does not support is +# the one case that is neither sent nor refused: `_check_valid_arg` skips it +# before it can reach `unsupported_params`, so no `UnsupportedParamsError` is +# raised, and `map_openai_params` only copies supported names, so it never +# reaches the wire either. The caller sees success and a param that did nothing. +# +# That is reported as issue #45015: `user` is only a supported param for models +# in OpenAI's own catalog (`gpt_transformation.py` adds it behind +# `is_openai_catalog_model`), so passing `user=` to a self-hosted +# OpenAI-compatible model silently drops it, and the proxy's per-customer spend +# attribution -- which reads `request_body["user"]` -- records nothing. The +# reporter found the `x-litellm-end-user-id` header by trial and error, because +# it bypasses param mapping entirely. +# +# Only params listed here warn. `stream`, `stream_options` and `max_retries` +# are transport controls rather than things a caller tracks the effect of, and +# warning on them would be noise on every request that sets one. +UNVALIDATED_PARAM_DROP_HINTS: Final = { + "user": ( + "`user` is only a supported param for models in OpenAI's catalog, so it is dropped here " + "without being sent or rejected. If you are attributing spend per end user through the " + "LiteLLM proxy, send the `x-litellm-end-user-id` header instead, which does not go through " + "provider param mapping." + ), +} + +# A bare `Final` satisfies LIT010 without putting a mutable `set[...]` in an +# annotation, which LIT001 counts; the parameterized constructor still gives the +# precise element type. `Final` binds the name, not the contents, so the set is +# mutated in place below, matching `PROVIDER_UNVALIDATED_PARAMS` above. +_unvalidated_param_warned: Final = set[tuple[str, str, str]]() + +# Bounded so a proxy serving a large model fleet cannot grow the set without +# limit. Past this many distinct (param, provider, model) triples the message +# has stopped being news, so warning simply stops rather than repeating. +_UNVALIDATED_PARAM_WARN_CAP: Final = 64 + + +def warn_unvalidated_param_dropped(param: str, custom_llm_provider: object, model: object) -> None: + """Warn once per (param, provider, model) that a drop-silently param was dropped. + + Called from `_check_valid_arg` at the point where both facts are known: the + provider does not list the param, and the param is exempt from raising. + """ + hint: Final = UNVALIDATED_PARAM_DROP_HINTS.get(param) + if hint is None: + return + key: Final = (param, str(custom_llm_provider), str(model)) + if key in _unvalidated_param_warned: + return + if len(_unvalidated_param_warned) >= _UNVALIDATED_PARAM_WARN_CAP: + return + _unvalidated_param_warned.add(key) + verbose_logger.warning( + "LiteLLM is not sending `%s` to provider=%s for model=%s: the model does not list it as a " + "supported param, and it is exempt from the unsupported-param error, so it is dropped " + "silently. %s", + param, + custom_llm_provider, + model, + hint, + ) + def provider_rejectable_params(passed_params: Mapping[str, object]) -> frozenset[str]: """The params a provider can actually be rejected for, i.e. the ones _check_valid_arg compares diff --git a/tests/unit/test_utils_get_optional_params.py b/tests/unit/test_utils_get_optional_params.py index 13a64577efb..30805a5ce0b 100644 --- a/tests/unit/test_utils_get_optional_params.py +++ b/tests/unit/test_utils_get_optional_params.py @@ -2097,3 +2097,136 @@ def test_supports_system_message_merges_system_prompt_into_user_message() -> Non ] assert map_system_message_pt(messages=messages) == [{"role": "user", "content": "Listen here! Hello there!"}] + + +def _drop_warnings(mock_warning): + """The formatted drop warnings only. + + `verbose_logger.warning` is shared, so asserting on a raw call count would + make these tests fail the day something unrelated in `get_optional_params` + logs a warning. Filter to this message and format it, since the assertions + are about what the message tells the caller. + """ + messages = [] + for call in mock_warning.call_args_list: + template = call.args[0] + if "is not sending" not in template: + continue + messages.append(template % call.args[1:]) + return messages + + +@pytest.fixture +def reset_unvalidated_param_warnings(): + """The drop warning is deduped for the life of the process. + + A test that asserts it fires has to start from an empty set, and must not + leave its own entries behind for the next one. + """ + from litellm.utils import _unvalidated_param_warned + + _unvalidated_param_warned.clear() + yield + _unvalidated_param_warned.clear() + + +def test_user_param_dropped_warns_for_non_catalog_model(reset_unvalidated_param_warnings): + """A param that is exempt from the unsupported-param error is still dropped. + + `user` is only a supported param for models in OpenAI's catalog, and it is in + PROVIDER_UNVALIDATED_PARAMS, so for any other model it is neither sent nor + refused. Reported as #45015, where per-customer spend attribution recorded + nothing and the caller had no way to see why. + """ + with patch("litellm.utils.verbose_logger.warning") as mock_warning: + optional_params = get_optional_params( + model="Qwen3.6-35B-A3B", + custom_llm_provider="openai", + user="customer-1", + ) + + assert "user" not in optional_params + + messages = _drop_warnings(mock_warning) + assert len(messages) == 1 + assert "`user`" in messages[0] + assert "Qwen3.6-35B-A3B" in messages[0] + # The workaround is the point of the message; without it the warning only + # tells the caller that something was lost, not what to do instead. + assert "x-litellm-end-user-id" in messages[0] + + +def test_user_param_drop_warning_is_deduped(reset_unvalidated_param_warnings): + """Once per (param, provider, model), not once per request.""" + with patch("litellm.utils.verbose_logger.warning") as mock_warning: + for _ in range(3): + get_optional_params( + model="Qwen3.6-35B-A3B", + custom_llm_provider="openai", + user="customer-1", + ) + + assert len(_drop_warnings(mock_warning)) == 1 + + +def test_user_param_not_warned_when_the_model_supports_it(reset_unvalidated_param_warnings): + """A catalog model sends `user`, so there is nothing to warn about.""" + with patch("litellm.utils.verbose_logger.warning") as mock_warning: + optional_params = get_optional_params( + model="gpt-4o", + custom_llm_provider="openai", + user="customer-1", + ) + + assert optional_params["user"] == "customer-1" + assert _drop_warnings(mock_warning) == [] + + +def test_warn_helper_stays_silent_for_an_exempt_param_with_no_hint( + reset_unvalidated_param_warnings, +): + """The exempt transport params must stay silent. + + `stream`, `stream_options` and `max_retries` are exempt from the same + unsupported-param check but are transport controls rather than things a + caller tracks the effect of, so they are deliberately absent from + UNVALIDATED_PARAM_DROP_HINTS. Without this the warning could be widened to + every exempt param and nothing would fail. + + The helper is called directly on purpose. For provider=openai all three are + *supported* params, so they never reach it through get_optional_params -- + asserting on that route passes without the guard ever running, which is + what the first version of this test did. + """ + from litellm.utils import _unvalidated_param_warned, warn_unvalidated_param_dropped + + with patch("litellm.utils.verbose_logger.warning") as mock_warning: + for param in ("stream", "stream_options", "max_retries"): + warn_unvalidated_param_dropped(param, "openai", "Qwen3.6-35B-A3B") + + assert _drop_warnings(mock_warning) == [] + # Nor may a param with no hint consume a slot against the cap. + assert _unvalidated_param_warned == set() + + +def test_warning_stops_once_the_cap_is_reached(reset_unvalidated_param_warnings): + """Past the cap the warning stops rather than growing the dedup set. + + A proxy serving a large model fleet would otherwise add a triple per + (param, provider, model) for the life of the process. + """ + from litellm.utils import ( + _UNVALIDATED_PARAM_WARN_CAP, + _unvalidated_param_warned, + warn_unvalidated_param_dropped, + ) + + for i in range(_UNVALIDATED_PARAM_WARN_CAP): + _unvalidated_param_warned.add(("user", "openai", f"filler-model-{i}")) + + with patch("litellm.utils.verbose_logger.warning") as mock_warning: + warn_unvalidated_param_dropped("user", "openai", "model-past-the-cap") + + assert _drop_warnings(mock_warning) == [] + assert ("user", "openai", "model-past-the-cap") not in _unvalidated_param_warned + assert len(_unvalidated_param_warned) == _UNVALIDATED_PARAM_WARN_CAP