diff --git a/litellm/utils.py b/litellm/utils.py index 72c37c3760e..12eb2ec78de 100644 --- a/litellm/utils.py +++ b/litellm/utils.py @@ -5096,6 +5096,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 @@ -5739,6 +5748,72 @@ _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 +# 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). +# +# 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 " + "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 + +# `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. + + 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, + _log_safe(custom_llm_provider), + _log_safe(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..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 @@ -2097,3 +2098,156 @@ 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: MagicMock) -> list[str]: + """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. + """ + 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() -> 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 + 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: 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 + 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: 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): + 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: 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( + 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: None, +) -> None: + """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: 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 + (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 + + +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]