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 1/2] 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 From 2bb5c6d46125b237e16a40410cab9187c898ef28 Mon Sep 17 00:00:00 2001 From: aayushbaluni <73417844+aayushbaluni@users.noreply.github.com> Date: Sun, 18 Oct 2026 15:01:38 +0530 Subject: [PATCH 2/2] fix: stop the drop warning carrying a forged log line CodeQL flagged py/log-injection on the two caller-controlled values this warning logs. `model` comes straight off the request, so a crafted name produced a second log line that reads as its own record: utils.py:5298 - LiteLLM is not sending `user` to provider=openai for model=gpt-4o WARNING: [auth] admin login succeeded from 10.0.0.1 Both values now go through a printable-only, length-bounded projection, the same treatment `_sanitize_correlation_id` gives a caller-set trace id. The crafted content still appears, inline on the one line, so the warning keeps naming the model that dropped the param. The regression test captures the formatted record rather than the call args, since that is where a forged line would show, and composes the control characters with chr() so the intent survives reformatting. It fails on the unsanitised version. Also from that review: the tests this PR adds are typed (LIT010 and strongly-typed params) and the 17-line preamble above the hint table is cut to 7 -- the failure history belongs in #45015. The 80 older tests in that file are left untyped and unformatted as they were. --- litellm/utils.py | 37 +++++++------- tests/unit/test_utils_get_optional_params.py | 51 ++++++++++++++------ 2 files changed, 56 insertions(+), 32 deletions(-) diff --git a/litellm/utils.py b/litellm/utils.py index d620bb45026..37b6a686c2b 100644 --- a/litellm/utils.py +++ b/litellm/utils.py @@ -5243,22 +5243,12 @@ _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. +# neither sent nor refused: `_check_valid_arg` skips it before it can reach +# `unsupported_params`, and `map_openai_params` only copies supported names, so +# the caller sees success and a param that did nothing (#45015). # -# 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. +# Only params listed here warn. `stream`, `stream_options` and `max_retries` are +# transport controls rather than things a caller tracks the effect of. UNVALIDATED_PARAM_DROP_HINTS: Final = { "user": ( "`user` is only a supported param for models in OpenAI's catalog, so it is dropped here " @@ -5279,6 +5269,19 @@ _unvalidated_param_warned: Final = set[tuple[str, str, str]]() # has stopped being news, so warning simply stops rather than repeating. _UNVALIDATED_PARAM_WARN_CAP: Final = 64 +# `model` and `custom_llm_provider` arrive from the request, so a caller could +# embed carriage returns, newlines or terminal escapes and forge whole log +# entries off the back of this warning (CodeQL py/log-injection), or repeat an +# oversized value on every line. Same treatment `_sanitize_correlation_id` +# gives a caller-set trace id. +_MAX_LOGGED_VALUE_LENGTH: Final = 128 + + +def _log_safe(value: object) -> str: + """Bound and strip a caller-controlled value before it reaches a log line.""" + printable: Final = "".join(ch for ch in str(value) if ch.isprintable()) + return printable[:_MAX_LOGGED_VALUE_LENGTH] + 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. @@ -5300,8 +5303,8 @@ def warn_unvalidated_param_dropped(param: str, custom_llm_provider: object, mode "supported param, and it is exempt from the unsupported-param error, so it is dropped " "silently. %s", param, - custom_llm_provider, - model, + _log_safe(custom_llm_provider), + _log_safe(model), hint, ) diff --git a/tests/unit/test_utils_get_optional_params.py b/tests/unit/test_utils_get_optional_params.py index 30805a5ce0b..a2c2fa67a85 100644 --- a/tests/unit/test_utils_get_optional_params.py +++ b/tests/unit/test_utils_get_optional_params.py @@ -1,4 +1,5 @@ import json +from collections.abc import Iterator from typing import Final from unittest.mock import MagicMock, patch @@ -2099,7 +2100,7 @@ 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): +def _drop_warnings(mock_warning: MagicMock) -> list[str]: """The formatted drop warnings only. `verbose_logger.warning` is shared, so asserting on a raw call count would @@ -2107,17 +2108,11 @@ def _drop_warnings(mock_warning): 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 + return [call.args[0] % call.args[1:] for call in mock_warning.call_args_list if "is not sending" in call.args[0]] @pytest.fixture -def reset_unvalidated_param_warnings(): +def reset_unvalidated_param_warnings() -> Iterator[None]: """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 @@ -2130,7 +2125,7 @@ def reset_unvalidated_param_warnings(): _unvalidated_param_warned.clear() -def test_user_param_dropped_warns_for_non_catalog_model(reset_unvalidated_param_warnings): +def test_user_param_dropped_warns_for_non_catalog_model(reset_unvalidated_param_warnings: None) -> None: """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 @@ -2156,7 +2151,7 @@ def test_user_param_dropped_warns_for_non_catalog_model(reset_unvalidated_param_ assert "x-litellm-end-user-id" in messages[0] -def test_user_param_drop_warning_is_deduped(reset_unvalidated_param_warnings): +def test_user_param_drop_warning_is_deduped(reset_unvalidated_param_warnings: None) -> None: """Once per (param, provider, model), not once per request.""" with patch("litellm.utils.verbose_logger.warning") as mock_warning: for _ in range(3): @@ -2169,7 +2164,7 @@ def test_user_param_drop_warning_is_deduped(reset_unvalidated_param_warnings): assert len(_drop_warnings(mock_warning)) == 1 -def test_user_param_not_warned_when_the_model_supports_it(reset_unvalidated_param_warnings): +def test_user_param_not_warned_when_the_model_supports_it(reset_unvalidated_param_warnings: None) -> None: """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( @@ -2183,8 +2178,8 @@ def test_user_param_not_warned_when_the_model_supports_it(reset_unvalidated_para def test_warn_helper_stays_silent_for_an_exempt_param_with_no_hint( - reset_unvalidated_param_warnings, -): + reset_unvalidated_param_warnings: None, +) -> None: """The exempt transport params must stay silent. `stream`, `stream_options` and `max_retries` are exempt from the same @@ -2209,7 +2204,7 @@ def test_warn_helper_stays_silent_for_an_exempt_param_with_no_hint( assert _unvalidated_param_warned == set() -def test_warning_stops_once_the_cap_is_reached(reset_unvalidated_param_warnings): +def test_warning_stops_once_the_cap_is_reached(reset_unvalidated_param_warnings: None) -> None: """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 @@ -2230,3 +2225,29 @@ def test_warning_stops_once_the_cap_is_reached(reset_unvalidated_param_warnings) 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 + + +def test_drop_warning_cannot_forge_a_log_line() -> None: + """A caller-controlled `model` must not be able to add log lines. + + `model` comes straight off the request and the warning puts it in a log + entry, so a carriage return or newline in it used to produce a second line + that reads as its own log record (CodeQL py/log-injection). The control + characters are composed with chr() so the intent survives any reformatting. + """ + from litellm.utils import _unvalidated_param_warned, warn_unvalidated_param_dropped + + crafted: Final = "gpt-4o" + chr(13) + chr(10) + "WARNING: [auth] admin login succeeded" + + _unvalidated_param_warned.clear() + with patch("litellm.utils.verbose_logger.warning") as mock_warning: + warn_unvalidated_param_dropped("user", "openai", crafted) + _unvalidated_param_warned.clear() + + messages: Final = _drop_warnings(mock_warning) + assert len(messages) == 1 + # The assertion that matters: the record stays one line. + assert chr(10) not in messages[0] + assert chr(13) not in messages[0] + # Still names the model, so sanitising has not made the warning useless. + assert "gpt-4o" in messages[0]