sgl-project/sglang · error · ValueError

Value error, parameter top_n should be larger than 0.

Error message

Value error, parameter top_n should be larger than 0.

What it means

EmbeddingRequest.validate_top_n rejects top_n values less than 1 (0 or negative). top_n asks for the top-N embedding results, so it must be a positive integer.

Source

Thrown at python/sglang/srt/entrypoints/openai/protocol.py:1416

    instruct: Optional[str] = Field(
        default=None,
        description="The instruct to the reranker model.",
    )
    top_n: Optional[int] = Field(
        default=None,
        description="Maximum number of documents to return. Defaults to returning all documents. "
        "If specified value is greater than the total number of documents, all documents will be returned.",
    )
    return_documents: bool = Field(
        default=True,
        description="Whether to return documents in the response. Only included when set to true.",
    )

    @field_validator("top_n")
    @classmethod
    def validate_top_n(cls, v):
        if v is not None and v < 1:
            raise ValueError("Value error, parameter top_n should be larger than 0.")
        return v

    def is_multimodal(self) -> bool:
        """Check if the request contains any multimodal content."""
        if isinstance(self.query, list):
            return True
        for doc in self.documents:
            if isinstance(doc, list):
                return True
        return False


class RerankResponse(BaseModel):
    score: float
    document: Optional[str] = None
    index: int
    meta_info: Optional[dict] = None

View on GitHub (pinned to 0132848349)

Solutions

1. Set top_n >= 1
2. Omit top_n to use the default
3. If you wanted 'all', pass the actual count of items

Example fix

// before
{"input": "text", "top_n": 0}
// after
{"input": "text", "top_n": 5}

if body.get("top_n") is not None:
    assert isinstance(body["top_n"], int) and body["top_n"] >= 1, "top_n must be >= 1"

def valid_top_n(n): return n is None or (isinstance(n, int) and n >= 1)

When it happens

Trigger: POST /v1/embeddings (or the embeddings endpoint using EmbeddingRequest) with top_n=0 or top_n=-3.

Common situations: Defaulting numeric params to 0 in client configs; passing -1 meaning 'all'; confusion with top_k sampling parameters elsewhere.

Related errors

• invalid reasoning effort: {effort!r}
• Exactly one of 'prompt' or 'messages' must be provided.
• Assistant tool call function.arguments must be a JSON object
• v_cache must be provided
• q can only be None when only_qv=True

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/ae745cf4b9d1405c. Report an issue: GitHub.