sgl-project/sglang · error · ValueError

`max_possible_layers` must be provided alongside `select_lay

Error message

`max_possible_layers` must be provided alongside `select_layers`

What it means

resolve_visual_encoder_outputs supports selecting intermediate layer outputs via select_layers, but it needs max_possible_layers (the checkpoint's full layer count) to map selected indices onto the possibly-truncated encoder output list. Calling with select_layers but no max_possible_layers is an API misuse.

Source

Thrown at python/sglang/srt/models/siglip2.py:391

        return hidden_states


def resolve_visual_encoder_outputs(
    encoder_outputs: torch.Tensor | list[torch.Tensor],
    post_layer_norm: Optional[nn.LayerNorm],
    select_layers: Optional[list[int]] = None,
    max_possible_layers: Optional[int] = None,
) -> torch.Tensor:
    """Resolve outputs from visual encoder based on select_layers."""
    if select_layers is None:
        if isinstance(encoder_outputs, list):
            encoder_outputs = encoder_outputs[-1]
        if post_layer_norm is not None:
            encoder_outputs = post_layer_norm(encoder_outputs)
        return encoder_outputs

    if max_possible_layers is None:
        raise ValueError(
            "`max_possible_layers` must be provided alongside `select_layers`"
        )

    if not isinstance(encoder_outputs, list):
        raise ValueError(
            "Expected encoder_outputs to be a list when select_layers is provided"
        )

    # Get the hidden states corresponding to the layer indices
    num_loaded_layers = len(encoder_outputs) - 1
    offset = max_possible_layers - num_loaded_layers
    hs_pool = [
        (
            encoder_outputs[layer_idx]
            if layer_idx >= 0
            else encoder_outputs[layer_idx + offset]
        )
        for layer_idx in select_layers

View on GitHub (pinned to 0132848349)

Solutions

Pass max_possible_layers=config.num_hidden_layers of the vision encoder alongside select_layers
If you don't need intermediate features, drop select_layers and take the final output
Update forked callers to the current helper signature

Example fix

# before
outs = resolve_visual_encoder_outputs(enc_out, select_layers=[5, 17])
# after
outs = resolve_visual_encoder_outputs(
    enc_out, select_layers=[5, 17],
    max_possible_layers=config.num_hidden_layers)

Defensive patterns

Strategy: validation

Validate before calling

if select_layers is not None:
    assert max_possible_layers is not None, "select_layers requires max_possible_layers"

Prevention

Wrap helper calls in a thin adapter that fills required kwargs from config

When it happens

Trigger: Calling resolve_visual_encoder_outputs(select_layers=[...]) without passing max_possible_layers from python/sglang/srt/models/siglip2.py:391.

Common situations: Custom multimodal wrappers or forks that call this helper directly; upstream refactors where a caller was updated to pass select_layers but not the new max_possible_layers argument.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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