sgl-project/sglang · error · ValueError

MiniMax-H3 quality="high" requires a resolved request plan

Error message

MiniMax-H3 quality="high" requires a resolved request plan

What it means

For non-warmup requests with quality="high", the stage must find a resolved MiniMax H3 request plan (via minimax_h3_plan_from_batch) before validating the exact workload. If no plan is attached to the batch, this error is raised.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/release_metadata.py:165

        if not isinstance(task, str) or not task.strip():
            raise ValueError("MiniMax H3 request task must be a non-empty string")
        self.metadata.canonical_task(task)
        if batch.num_inference_steps < 2:
            raise ValueError(
                "MiniMax H3 requires num_inference_steps >= 2 because its "
                "video/audio sigma schedules include both interval endpoints"
            )
        quality = getattr(batch.sampling_params, "quality", "lossless")
        if quality not in QUALITY_LEVELS:
            raise ValueError(
                f"quality must be one of {list(QUALITY_LEVELS)}, got {quality!r}"
            )
        high_quality = quality == "high"
        if high_quality and not batch.is_warmup:
            server_args.pipeline_config.validate_quality_deployment(server_args)
            plan = minimax_h3_plan_from_batch(batch)
            if plan is None:
                raise ValueError(
                    'MiniMax-H3 quality="high" requires a resolved request plan'
                )
            shape = plan.shape
            actual = {
                "task": plan.task,
                "width": int(shape["width"]),
                "height": int(shape["height"]),
                "fps": int(shape["fps"]),
                "frame_count": int(shape["frame_count"]),
                "num_inference_steps": int(batch.num_inference_steps),
                "flow_shift": float(
                    plan.flow_shift
                    if plan.flow_shift is not None
                    else plan.default_flow_shift
                ),
                "audio_flow_shift": float(
                    plan.audio_flow_shift
                    if plan.audio_flow_shift is not None

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure the MiniMax H3 plan resolution stage runs before this admission stage in the pipeline
2. Verify the request carries the inputs plan resolution needs (media/shape metadata)
3. If quality="high" is not intended, drop to the default "lossless" quality

Example fix

# before
# admission stage runs before plan resolution; plan is None
# after
# pipeline order: plan_resolution -> partition_admission

if getattr(sp, "quality", "lossless") == "high" and not req.is_warmup:
    assert minimax_h3_plan_from_batch(req) is not None, "plan missing before admission"

When it happens

Trigger: quality="high" and batch.is_warmup is False but minimax_h3_plan_from_batch(batch) returns None — the request never went through plan resolution.

Common situations: Bypassing the planning stage in a custom pipeline, a pipeline ordering bug where admission runs before planning, or a plan attachment silently failing for an unusual request shape.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• MiniMax-H3 quality="high" is validated only for {_MINIMAX_H3
• fl2va requires first_frame, last_frame, or both
• ref2va requires at least one of reference_image, reference_v
• t2va takes no conditioning inputs; pick another task
• MiniMax-H3 quality="high" is validated only for the strict 4

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