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.
This commit is contained in:
aayushbaluni 2026-10-16 13:23:21 +05:30
parent 4e49394ade
commit a179d1365e
2 changed files with 205 additions and 0 deletions

View file

@ -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

View file

@ -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