fix(proxy): warn on uvicorn below 0.37 when multi-worker boots cannot get the longer healthcheck
Some checks failed
LiteLLM Rust DB / db-queries (push) Has been cancelled
LiteLLM Rust / rust-lint (push) Has been cancelled
LiteLLM Rust / rust-test (push) Has been cancelled
LiteLLM Rust / rust-wheel (push) Has been cancelled
Terraform Modules / fmt, validate, test (aws) (push) Has been cancelled
Terraform Modules / fmt, validate, test (gcp) (push) Has been cancelled
Terraform Provider / gofmt, vet, build, test (push) Has been cancelled
Terraform Provider / Provider endpoints vs proxy OpenAPI schema (push) Has been cancelled

uvicorn 0.33 to 0.36 has no timeout_worker_healthcheck, so the 60 s default never reaches it and a slow worker start still crash-loops with no hint. Print an upgrade warning when the proxy runs more than one uvicorn worker on such a version, keep granian out of the uvicorn-only path, and type the new tests.
This commit is contained in:
mateo-berri 2026-10-28 19:08:47 -07:00
parent c9f53800fb
commit cf5e091f7b
2 changed files with 71 additions and 8 deletions

View file

@ -340,6 +340,7 @@ class ProxyInitializationHelpers:
log_config: str | None = None,
keepalive_timeout: int | None = None,
timeout_worker_healthcheck: int | None = None,
num_workers: int = 1,
) -> dict:
"""
Get the arguments for `uvicorn` worker
@ -385,6 +386,12 @@ class ProxyInitializationHelpers:
f"requires uvicorn>=0.37.0, but installed uvicorn=={uvicorn.__version__}. "
f"Ignoring the flag.\033[0m",
)
elif num_workers > 1:
print_startup_message(
f"\033[1;33mLiteLLM Proxy: uvicorn=={uvicorn.__version__} gives each worker a fixed 5 s to answer "
f"its health ping, so a worker that starts slower is killed with 'Child process died'. Install "
f"uvicorn>=0.37.0 to get the {DEFAULT_WORKER_HEALTHCHECK_TIMEOUT_SECONDS} s default.\033[0m",
)
return uvicorn_args
_get_default_unvicorn_init_args = get_default_unvicorn_init_args
@ -1667,13 +1674,14 @@ def run_server(
f"(pid {metrics_process.pid})\033[0m"
)
running_uvicorn: Final = run_gunicorn is False and run_hypercorn is False
running_uvicorn: Final = run_gunicorn is False and run_hypercorn is False and run_granian is False
uvicorn_args: Final = ProxyInitializationHelpers.get_default_unvicorn_init_args(
host=host,
port=port,
log_config=log_config,
keepalive_timeout=keepalive_timeout,
timeout_worker_healthcheck=(timeout_worker_healthcheck if running_uvicorn else None),
num_workers=(num_workers if running_uvicorn else 1),
)
# Optional: recycle uvicorn workers after N requests
if max_requests_before_restart is not None:

View file

@ -164,28 +164,40 @@ class TestProxyInitializationHelpers:
("flag_value", "expected"),
[(None, DEFAULT_WORKER_HEALTHCHECK_TIMEOUT_SECONDS), (15, 15)],
)
def test_uvicorn_worker_healthcheck_timeout_reaches_uvicorn(self, flag_value, expected):
def test_uvicorn_worker_healthcheck_timeout_reaches_uvicorn(self, flag_value: int | None, expected: int):
args: Final = ProxyInitializationHelpers._get_default_unvicorn_init_args(
"localhost", 8000, timeout_worker_healthcheck=flag_value
)
assert uvicorn.Config(**args).timeout_worker_healthcheck == expected
def test_worker_healthcheck_timeout_on_uvicorn_without_the_parameter(self, capsys):
def test_worker_healthcheck_timeout_on_uvicorn_without_the_parameter(
self, capsys: pytest.CaptureFixture[str]
):
class _OldUvicornConfig:
def __init__(self, timeout_keep_alive=None):
def __init__(self, timeout_keep_alive: int | None = None):
pass
with patch("uvicorn.Config", _OldUvicornConfig):
default_args: Final = ProxyInitializationHelpers._get_default_unvicorn_init_args("localhost", 8000)
assert "timeout_worker_healthcheck" not in default_args
single_worker_args: Final = ProxyInitializationHelpers._get_default_unvicorn_init_args("localhost", 8000)
assert "timeout_worker_healthcheck" not in single_worker_args
assert capsys.readouterr().out == ""
multi_worker_args: Final = ProxyInitializationHelpers._get_default_unvicorn_init_args(
"localhost", 8000, num_workers=2
)
assert "timeout_worker_healthcheck" not in multi_worker_args
multi_worker_output: Final = capsys.readouterr().out
assert "fixed 5 s" in multi_worker_output
assert "uvicorn>=0.37.0" in multi_worker_output
flagged_args: Final = ProxyInitializationHelpers._get_default_unvicorn_init_args(
"localhost", 8000, timeout_worker_healthcheck=15
"localhost", 8000, timeout_worker_healthcheck=15, num_workers=2
)
assert "timeout_worker_healthcheck" not in flagged_args
assert "requires uvicorn>=0.37.0" in capsys.readouterr().out
flagged_output: Final = capsys.readouterr().out
assert "requires uvicorn>=0.37.0" in flagged_output
assert "fixed 5 s" not in flagged_output
@pytest.mark.parametrize(
("raw_timeout", "expected"),
@ -1557,6 +1569,7 @@ class TestProxyInitializationHelpers:
log_config=None,
keepalive_timeout=30,
timeout_worker_healthcheck=None,
num_workers=1,
)
mock_uvicorn_run.assert_called_once()
@ -1633,6 +1646,7 @@ class TestProxyInitializationHelpers:
log_config=None,
keepalive_timeout=None,
timeout_worker_healthcheck=15,
num_workers=1,
)
@patch("uvicorn.run")
@ -2442,6 +2456,47 @@ class TestQueryEngineReaperWiring:
result = runner.invoke(run_server, args)
return result, mock_uvicorn_run, mock_start_reaper
@pytest.mark.parametrize(
("args", "warns"),
[
(["--local", "--num_workers", "2"], True),
(["--local", "--num_workers", "1"], False),
(["--local", "--num_workers", "2", "--run_granian"], False),
],
)
def test_old_uvicorn_warns_only_for_multi_worker_uvicorn(self, args: list[str], warns: bool):
from click.testing import CliRunner
from litellm.proxy.proxy_cli import run_server
class _OldUvicornConfig:
def __init__(self, timeout_keep_alive: int | None = None):
pass
clean_env: Final = {k: v for k, v in os.environ.items() if k not in ("DATABASE_URL", "DIRECT_URL")}
with (
patch.dict(os.environ, clean_env, clear=True),
patch.dict(
"sys.modules",
{
"proxy_server": MagicMock(
app=MagicMock(),
ProxyConfig=MagicMock(),
KeyManagementSettings=MagicMock(),
save_worker_config=MagicMock(),
)
},
),
patch("uvicorn.Config", _OldUvicornConfig),
patch("uvicorn.run"),
patch("litellm.proxy.proxy_cli.start_query_engine_reaper"),
patch("litellm.proxy.proxy_cli.ProxyInitializationHelpers.init_granian_server"),
):
result: Final = CliRunner().invoke(run_server, args)
assert result.exit_code == 0, f"exit_code={result.exit_code}, output={result.output}"
assert ("uvicorn>=0.37.0" in result.output) is warns
def test_multi_worker_uvicorn_starts_reaper(self):
result, mock_uvicorn_run, mock_start_reaper = self._invoke_run_server(
["--local", "--num_workers", "2"]