sgl-project/sglang · error · ValueError

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

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.

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)

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

• {cpath} has unknown fields: {sorted(unknown)}
• 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!
• canonical request must be a mapping

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