[Core][Feat] Add max-waiting-queue-length parameter to reject requests when waiting queue is full

[chaunceyjiang]

Essential Elements of an Effective PR Description Checklist

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan, such as providing test command.
• The test results, such as pasting the results comparison before and after, or e2e results
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.

Purpose

Feature implementation #18826

Test Plan

Test Result

(Optional) Documentation Update

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors. You can run other CI tests on top of those by going to your fastcheck build on Buildkite UI (linked in the PR checks section) and unblock them. If you do not have permission to unblock, ping simon-mo or khluu to add you in our Buildkite org.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

🚀

[gemini-code-assist]

Code Review

This pull request introduces a mechanism to limit the waiting queue size and reject new requests when the queue is full, which is a valuable feature for managing server load. The implementation correctly adds the max-waiting-queue-length parameter and propagates the SchedulerWaitingQueueFullError through the system to the API layer.

I've identified a few areas for improvement, mainly related to removing leftover debugging statements and simplifying some validation logic. These changes will help ensure the code is clean and production-ready.

[chaunceyjiang]

Test

vllm serve /home/jovyan/qwen3-8b --enable-auto-tool-choice --tool-call-parser hermes --reasoning-parser qwen3 --max-waiting-queue-length 1 --disable-log-requests

client

hey -n 100 -c 10 -m POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello! What can you do?"}
    ],
    "temperature": 0.7
  }' \
  http://localhost:8000/v1/chat/completions

vllm log :

....
NFO:     127.0.0.1:54710 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:54742 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:54672 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:54688 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO 07-22 15:12:07 [loggers.py:118] Engine 000: Avg prompt throughput: 39.0 tokens/s, Avg generation throughput: 678.4 tokens/s, Running: 5 reqs, Waiting: 0 reqs, GPU KV cache usage: 0.3%, Prefix cache hit rate: 60.6%
INFO:     127.0.0.1:54742 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:54696 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:54744 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:54672 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:32976 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:32992 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:33002 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:32992 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:32976 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:32992 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:32976 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:33028 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:33028 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:32976 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:32976 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:54688 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:54742 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:32992 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:32966 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:33002 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:33046 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:33002 - "POST /v1/chat/completions HTTP/1.1" 503 Service Unavailable
INFO:     127.0.0.1:32960 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:33016 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:54688 - "POST /v1/chat/completions HTTP/1.1" 200 OK
INFO:     127.0.0.1:33026 - "POST /v1/chat/completions HTTP/1.1" 200 OK
....

[chaunceyjiang]

Hi @robertgshaw2-redhat @chudyandrej PTAL.

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @chaunceyjiang.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork