sgl-project/sglang · error · ValueError

canonical request must be a mapping

Error message

canonical request must be a mapping

What it means

minimax_h3_resolve_plan expects the already-validated canonical request as a Mapping. Passing a JSON string, list, or object without Mapping interface fails this early isinstance check.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/resolved_plan.py:261

            shape["size_mode"] = "deferred"
            return shape
        aspect_ratio = auto_aspect_ratio
        shape["geometry_source"] = auto_geometry_source or "policy_default"
    ar_w, ar_h = _parse_aspect_ratio(aspect_ratio)
    shape.update(
        minimax_h3_resolve_spatial_shape(
            width=ar_w,
            height=ar_h,
            base_short_edge=base_short_edge,
        )
    )
    return shape


def minimax_h3_resolve_plan(canonical: Mapping[str, Any]) -> MiniMaxH3ResolvedPlan:
    """Canonical request (already validated) -> ResolvedPlan."""
    if not isinstance(canonical, Mapping):
        raise ValueError("canonical request must be a mapping")
    allowed_keys = {
        "schema",
        "task",
        "prompt",
        "conditions",
        "target",
        "seed",
        "flow_shift",
        "audio_flow_shift",
    }
    unknown = set(canonical) - allowed_keys
    if unknown:
        raise ValueError(f"canonical request has unknown fields: {sorted(unknown)}")
    for key in ("schema", "task", "prompt", "conditions", "target"):
        if key not in canonical:
            raise ValueError(f"canonical request missing {key!r}")
    profile = minimax_h3_task_profile(str(canonical["task"]))
    conditions = canonical["conditions"]

View on GitHub (pinned to 0132848349)

Solutions

1. json.loads the payload before calling resolve_plan
2. Pass the dict produced by minimax_h3_validate_canonical_request directly

Example fix

# before
plan = minimax_h3_resolve_plan(raw_json_text)
# after
plan = minimax_h3_resolve_plan(json.loads(raw_json_text))

from collections.abc import Mapping
def is_mapping(v): return isinstance(v, Mapping)

from collections.abc import Mapping
def is_canonical_mapping(v) -> bool: return isinstance(v, Mapping)

null

When it happens

Trigger: Calling minimax_h3_resolve_plan('{"task":...}') with a serialized JSON string, a list of requests, or a custom object that is not a collections.abc.Mapping.

Common situations: Forgetting json.loads after transport/deserialization; double-encoding the payload; passing the raw HTTP body through.

Related errors

• target.aspect_ratio must be 'W:H' or 'auto', got {value!r}
• target.aspect_ratio must be integer 'W:H', got {value!r}
• target.aspect_ratio components must be positive, got {value!
• target.short_edge must be an integer, got {value!r}
• shape width and height must be positive finite numbers

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