sgl-project/sglang · error · ValueError

{cpath} has unknown fields: {sorted(unknown)}

Error message

{cpath} has unknown fields: {sorted(unknown)}

What it means

A condition object contains fields outside _ALLOWED_CONDITION_KEYS. The validator enforces a closed schema so typos and transport-layer extras fail fast.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py:192

        and len(conditions) > profile.max_condition_count
    ):
        raise ValueError(
            f"{path} allows at most {profile.max_condition_count} entries "
            f"for task {profile.task!r}, got {len(conditions)}"
        )

    aligned_frame_count = (
        minimax_h3_align_frame_count(frame_count) if frame_count is not None else None
    )
    normalized: list[dict[str, Any]] = []
    seen_frame_indices: dict[int, int] = {}
    for index, cond in enumerate(conditions):
        cpath = f"{path}[{index}]"
        if not isinstance(cond, Mapping):
            raise ValueError(f"{cpath} must be an object")
        unknown = set(cond) - _ALLOWED_CONDITION_KEYS
        if unknown:
            raise ValueError(f"{cpath} has unknown fields: {sorted(unknown)}")
        role = _require_str(cond.get("role"), f"{cpath}.role")
        if role not in (
            MINIMAX_H3_CONDITION_ROLE_KEYFRAME,
            MINIMAX_H3_CONDITION_ROLE_REFERENCE,
        ):
            raise ValueError(
                f"{cpath}.role must be keyframe or reference, " f"got {role!r}"
            )
        cond_type = _require_str(cond.get("type"), f"{cpath}.type")
        try:
            rule = profile.rule_for(role=role, condition_type=cond_type)
        except ValueError as exc:
            raise ValueError(f"{cpath}: {exc}") from exc
        uri = _require_str(cond.get("uri"), f"{cpath}.uri")

        entry: dict[str, Any] = {"type": cond_type, "uri": uri, "role": role}
        if rule.requires_frame_index:
            frame_index = _require_int(cond.get("frame_index"), f"{cpath}.frame_index")

View on GitHub (pinned to 0132848349)

Solutions

1. Remove/rename the unknown fields to the allowed set (role, type, uri, frame_index, start_time_seconds, ...)
2. Check _ALLOWED_CONDITION_KEYS for the exact supported schema
3. Upgrade the server if a newer client legitimately adds fields

Example fix

// before
{"role": "keyframe", "type": "image", "url": "f0.png"}
// after
{"role": "keyframe", "type": "image", "uri": "f0.png"}

allowed = {'role', 'type', 'uri', 'frame_index', 'start_time_seconds'}
extra = set(cond) - allowed
if extra:
    cond = {k: v for k, v in cond.items() if k in allowed}

When it happens

Trigger: Adding fields like 'frameIdx', 'timestamp', or 'url' (instead of 'uri') to a condition.

Common situations: Client SDK version drift adding new fields the server schema doesn't know; typos in field names; embedding metadata on conditions.

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

• tar material URI header must be a JSON object
• {path}.kind must be a non-empty string
• {path} must be a list
• {path} must be empty for task {profile.task!r} (got {len(con
• {path} requires at least one entry for task {profile.task!r}

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