sgl-project/sglang · error · ValueError

items must be provided

Error message

items must be provided

What it means

score_request requires the items argument; when items is None the call is rejected immediately after the label check. items carries the candidate texts/sequences to score against the query.

Source

Thrown at python/sglang/srt/managers/tokenizer_manager_score_mixin.py:484

           Multi-item scoring works with both text and pre-tokenized inputs:
           - Text: query<delimiter_text>item1<delimiter_text>item2<delimiter_text>item3<delimiter_text>
           - Tokens: query<delimiter_token_id>item1<delimiter_token_id>item2<delimiter_token_id>item3<delimiter_token_id>

        Supports two model types:
        - Generation (CausalLM): Requires label_token_ids; returns logprob-based scores.
        - SequenceClassification: label_token_ids is optional; returns pooled class logits.

        return_pooled_hidden_states is only supported for non-generation models
        (SequenceClassification, RewardModel); raises ValueError for CausalLM.
        """
        is_generation = self.is_generation

        if is_generation and label_token_ids is None:
            raise ValueError(
                "label_token_ids is required for generation (CausalLM) models."
            )
        if items is None:
            raise ValueError("items must be provided")
        if not items:
            return ScoreResult(scores=[], prompt_tokens=0)

        has_embeds = (
            query_embed_overrides is not None or item_embed_overrides is not None
        )
        if has_embeds and embed_override_token_id is None:
            raise ValueError(
                "embed_override_token_id is required when query_embed_overrides "
                "or item_embed_overrides are supplied."
            )
        if item_first and has_embeds:
            raise ValueError("item_first is not supported when embeddings are supplied")
        if item_embed_overrides is not None and len(item_embed_overrides) != len(items):
            raise ValueError(
                f"item_embed_overrides length ({len(item_embed_overrides)}) "
                f"must match items length ({len(items)})."
            )

View on GitHub (pinned to 0132848349)

Solutions

1. Pass items as a non-empty list of candidate strings or token-id lists
2. If items==[] is intended (empty batch), that returns an empty ScoreResult rather than erroring — but None is always invalid
3. Audit call sites built via kwargs unpacking to ensure items is populated

Example fix

# before
result = engine.score_request(query="query text")

# after
result = engine.score_request(query="query text", items=["candidate 1", "candidate 2"])

if items is None:
    raise ValueError("items is required for score_request")
# or: items = items or []

def has_items(kwargs: dict) -> bool:
    return kwargs.get("items") is not None

When it happens

Trigger: Calling score/score_request with items=None (omitted positional or explicit None), e.g. when only a query is passed.

Common situations: Optional/defaulted parameters left None after refactoring; client code assuming single-input scoring like embedding APIs; partial dict unpacking that drops items.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• v_cache must be provided
• q must be provided unless qv is provided with only_qv=True
• mask_block_cnt and mask_block_idx must be provided for block
• LoRA batch_info must provide max_len or seg_lens.
• kv-canary: launch_canary_plan_kernels_torch_reference requir

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