vllm-project/vllm · error · Error

`min_tokens` must be less than or equal to `max_tokens`, got

Error message

`min_tokens` must be less than or equal to `max_tokens`, got min_tokens={min_tokens}, max_tokens={max_tokens}

What it means

Thrown by the Rust text-frontend when lowering a completion/chat request: after `max_tokens` is resolved (request value, server default, or model-length-derived default via `resolve_max_tokens`) and `min_tokens` defaults to 0, the check `min_tokens > max_tokens` fails (rust/src/text/src/lower.rs:144). It is classified as a request-validation error (`is_request_validation_error` returns true), so the HTTP layer maps it to a 400-style client error, not a server fault.

Source

Thrown at rust/src/text/src/error.rs:31

pub enum Error {
    #[error("tokenizer error: {0}")]
    Tokenizer(String),
    #[error("text request `{request_id}` must contain at least one prompt token ID")]
    EmptyPromptTokenIds { request_id: String },
    #[error("text request `{request_id}` stop strings cannot be empty")]
    EmptyStopString { request_id: String },
    #[error(
        "this model's maximum context length is {max_model_len} tokens, \
         but the prompt contains {prompt_len} input tokens"
    )]
    PromptTooLong { max_model_len: u32, prompt_len: u32 },
    #[error(transparent)]
    Logprobs(#[from] LogprobsError),
    #[error(transparent)]
    TokenIds(#[from] TokenIdsError),
    #[error(transparent)]
    SamplingParams(#[from] SamplingParamsError),
    #[error(
        "`min_tokens` must be less than or equal to `max_tokens`, \
         got min_tokens={min_tokens}, max_tokens={max_tokens}"
    )]
    MinTokensExceedsMaxTokens { min_tokens: u32, max_tokens: u32 },
    #[error("`thinking_token_budget` must be a non-negative integer or -1 for unlimited.")]
    InvalidThinkingTokenBudget,
    #[error("invalid repetition detection params: {message}")]
    InvalidRepetitionDetection { message: String },
    #[error("text request stream `{request_id}` closed before terminal output")]
    StreamClosedBeforeTerminalOutput { request_id: String },
    #[error(transparent)]
    Llm(#[from] LlmError),
    #[error(transparent)]
    EngineCore(#[from] EngineCoreError),
}

pub type Result<T> = std::result::Result<T, Error>;

View on GitHub (pinned to c794754062)

Solutions

1. Set min_tokens <= max_tokens (or omit min_tokens entirely; it defaults to 0)
2. If you need a longer guaranteed minimum output, raise max_tokens accordingly
3. Check that prompt_len + min_tokens does not exceed max_model_len; shorten the prompt or increase the model context if the derived max_tokens is the constraint

Example fix

// before
params.min_tokens = 500;
params.max_tokens = 200; // or unset, derived from remaining context

// after
params.min_tokens = 200;
params.max_tokens = 500;

let effective_max = max_tokens.unwrap_or(max_model_len.saturating_sub(prompt_len));
if let Some(min_tokens) = request.min_tokens {
    assert!(min_tokens <= effective_max,
        "min_tokens {} exceeds effective max_tokens {}", min_tokens, effective_max);
}

fn is_min_tokens_error(e: &Error) -> bool {
    matches!(e, Error::MinTokensExceedsMaxTokens { .. })
}

match lower_request(params) {
    Err(Error::MinTokensExceedsMaxTokens { min_tokens, max_tokens }) => {
        return bad_request(format!("min_tokens {min_tokens} > max_tokens {max_tokens}"));
    }
    other => other,
}

When it happens

Trigger: Calling the completions/chat API with `min_tokens` greater than the effective `max_tokens`. The effective max_tokens may be smaller than requested: it is capped by `max_model_len - prompt_len`, so a long prompt plus a modest `min_tokens` can trigger it even when the caller never set max_tokens explicitly.

Common situations: Clients porting from another engine that clamps instead of rejecting; setting `min_tokens` high to force long outputs while forgetting the server's default max_tokens; long prompts that shrink the derived max_tokens below min_tokens.

Related errors

• `thinking_token_budget` must be a non-negative integer or -1
• {parameter} must be a finite number, got {value}
• {parameter} must be in {expected}, got {value}
• max_logprobs must be non-negative or -1, got {}
• data parallel size must be at least 1

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/00556812e542aa30. Report an issue: GitHub.