sgl-project/sglang · error · ValueError

canonical request has unknown fields

Error message

canonical request has unknown fields: {sorted(unknown)}

What it means

The canonical request passed to minimax_h3_resolve_plan contains fields outside the allowed key set (schema, task, prompt, conditions, target, seed, flow_shift, audio_flow_shift, ...). Unknown keys are rejected to catch schema drift between validation and plan resolution.

Solutions

1. Remove or rename unknown fields to match the allowed key set printed in the error
2. Route requests through minimax_h3_validate_canonical_request so the canonical dict is built by the library
3. Align validator and resolver versions (same package version)

Example fix

# before
resolve_plan({**canonical, "model": "minimax-h3"})
# after
resolve_plan(canonical)

ALLOWED = {"schema","task","prompt","conditions","target","seed","flow_shift","audio_flow_shift"}
def no_unknown_fields(canon): return not (set(canon) - ALLOWED)

null

null

When it happens

Trigger: Calling minimax_h3_resolve_plan with a dict containing extra keys such as 'model', 'metadata', or a typo like 'promt', or a stale field removed in the current version.

Common situations: Version mismatch where a newer validator emits a field the older resolver doesn't allow (or vice versa); hand-built canonical dicts that skip the validator; internal fields leaking through from transport.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• canonical request must be a mapping
• has unknown fields
• target.aspect_ratio components must be positive, got
• target.aspect_ratio must be integer 'W:H', got
• target.aspect_ratio must be 'W:H' or 'auto', got

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

Appendix: source

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

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"]
    keyframe_conditions = (
        [
            condition
            for condition in conditions
            if isinstance(condition, Mapping) and condition.get("role") == "keyframe"
        ]
        if isinstance(conditions, (list, tuple))
        else []
    )
    if profile.task == "fl2va" or keyframe_conditions:
        signatures = (
            [
                (

View on GitHub (pinned to 0132848349)