sgl-project/sglang · critical · ValueError

MiniMax H3 Qwen3-VL encoders smaller than 32B require --comp

Error message

MiniMax H3 Qwen3-VL encoders smaller than 32B require --component-paths.conditioning_projection

What it means

For MiniMax H3 Qwen3-VL encoders whose hidden size isn't the 32B value or which have fewer layers than the required tap layer, an external conditioning projection checkpoint must be supplied via --component-paths.conditioning_projection. Without it the model cannot extract conditioning features.

Source

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

    # Comfy packs the vision tower across whole tensors rather than rows. Keep
    # its language/vocabulary matrices packed and restore this smaller tower.
    gguf_dequantize_prefixes = ("visual.", "model.visual.")

    @classmethod
    def configure_component_paths(
        cls,
        config: MiniMaxH3Qwen3VLConfig,
        component_paths: dict[str, str],
    ) -> None:
        arch = config.arch_config
        source = component_paths.get("conditioning_projection")
        if source is None:
            if (
                int(arch.hidden_size) != MINIMAX_H3_QWEN3VL_HIDDEN_DIM
                or int(arch.checkpoint_num_hidden_layers)
                < MINIMAX_H3_QWEN3VL_SELECTED_LM_LAYER
            ):
                raise ValueError(
                    "MiniMax H3 Qwen3-VL encoders smaller than 32B require "
                    "--component-paths.conditioning_projection"
                )
            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}"

View on GitHub (pinned to 0132848349)

Solutions

1. Add --component-paths.conditioning_projection <path-to-projection.safetensors> to server args
2. If you intend to run the 32B model, verify the checkpoint/config actually has the 32B hidden size and layer count
3. Double-check the config.json hidden_size and num_hidden_layers of the loaded encoder

Example fix

# before
server_args = ServerArgs(model_path="minimax-h3-qwen3vl-small")
# after
server_args = ServerArgs(
    model_path="minimax-h3-qwen3vl-small",
    component_paths={"conditioning_projection": "/models/h3_proj.safetensors"},
)

hidden = arch.hidden_size
layers = arch.checkpoint_num_hidden_layers
needs_proj = hidden != MINIMAX_H3_QWEN3VL_HIDDEN_DIM or layers < MINIMAX_H3_QWEN3VL_SELECTED_LM_LAYER
if needs_proj:
    assert args.component_paths.get("conditioning_projection"), "smaller H3 models require --component-paths.conditioning_projection"

When it happens

Trigger: configure_component_paths called with source=None while arch.hidden_size != MINIMAX_H3_QWEN3VL_HIDDEN_DIM or checkpoint_num_hidden_layers < MINIMAX_H3_QWEN3VL_SELECTED_LM_LAYER.

Common situations: Running a smaller MiniMax H3 variant (non-32B) without providing the projection component path; misconfigured server args where conditioning_projection was omitted.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• MiniMax-H3 on MPS requires synchronous layerwise offload for
• MiniMax-H3 MPS execution does not support torch.compile; pas
• MiniMax-H3 ring parallelism requires the FlashAttention back
• MiniMax H3 AdaLN cache max_plan_width must be positive; set
• H3 conditioning projection {bias_name} has shape {tuple(bias

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