sgl-project/sglang · critical · ValueError

H3 conditioning projection tap {tap} is outside the selected

Error message

H3 conditioning projection tap {tap} is outside the selected encoder's {int(arch.checkpoint_num_hidden_layers)} layers

What it means

The projection checkpoint records a 'tap' layer index (which encoder layer to read conditioning features from), and it must lie in [1, checkpoint_num_hidden_layers] of the selected encoder. An out-of-range tap means the encoder has fewer layers than the projection expects.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/encoders/minimax_h3_qwen3vl.py:250

                )
            return

        projection_path = materialize_weight(resolve_weight(source))
        tap, input_dim, output_dim = MiniMaxH3ConditioningProjection.inspect(
            projection_path
        )
        if input_dim != int(arch.hidden_size):
            raise ValueError(
                f"H3 conditioning projection expects encoder width {input_dim}, "
                f"but the selected text encoder has width {int(arch.hidden_size)}"
            )
        if output_dim != MINIMAX_H3_QWEN3VL_HIDDEN_DIM:
            raise ValueError(
                f"H3 conditioning projection must output width "
                f"{MINIMAX_H3_QWEN3VL_HIDDEN_DIM}, got {output_dim}"
            )
        if tap <= 0 or tap > int(arch.checkpoint_num_hidden_layers):
            raise ValueError(
                f"H3 conditioning projection tap {tap} is outside the selected "
                f"encoder's {int(arch.checkpoint_num_hidden_layers)} layers"
            )
        arch.conditioning_projection_path = projection_path
        arch.num_hidden_layers = tap
        arch.text_config.num_hidden_layers = tap

    def should_materialize_checkpoint_weight(self, name: str) -> bool:
        name = _map_checkpoint_name(name)
        return (
            "rotary_emb.inv_freq" not in name
            and not _is_unconsumed_checkpoint_weight(name, self.selected_lm_layer)
        )

    def __init__(self, config: MiniMaxH3Qwen3VLConfig) -> None:
        super().__init__(config)
        arch = config.arch_config
        selected_layer = int(arch.text_config.num_hidden_layers)

View on GitHub (pinned to 0132848349)

Solutions

Use a projection whose tap layer exists in the selected encoder (tap <= num layers)
Serve the full-depth encoder the projection was exported from

Defensive patterns

Strategy: validation

Validate before calling

tap, _, _ = MiniMaxH3ConditioningProjection.inspect(path)
assert 0 < tap <= arch.checkpoint_num_hidden_layers

Prevention

Verify encoder layer count covers the projection's tap layer
Log tap and layer counts at startup for auditability

When it happens

Trigger: configure_component_paths where inspect()'s tap value is <= 0 or > arch.checkpoint_num_hidden_layers.

Common situations: Pairing a projection built for a deeper encoder with a shallower one; truncated encoder checkpoint with fewer layers.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

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