sgl-project/sglang · error · ValueError

{kind} state payload requires transitions

Error message

{kind} state payload requires transitions

What it means

Raised by _control_state_transitions_from_event_payload when parsing a realtime control event: the payload for a control-state event kind must contain a 'transitions' key whose value is a JSON list. Missing, null, or non-list transitions are rejected.

Source

Thrown at python/sglang/multimodal_gen/runtime/realtime/control_signals.py:120

                normalize_state_payload=normalize_state_payload,
            ),
        )
    return ParsedControlEventPayload(
        mode="script",
        payload=validate_script_payload(payload),
    )


def _control_state_transitions_from_event_payload(
    payload: dict[str, Any],
    *,
    event_id: int | None,
    kind: str,
    normalize_state_payload: ControlStatePayloadNormalizer,
) -> list[ControlStateTransition]:
    transitions = payload.get("transitions")
    if not isinstance(transitions, list):
        raise ValueError(f"{kind} state payload requires transitions")
    result = []
    for transition in transitions:
        if not isinstance(transition, dict):
            raise ValueError(f"{kind} transition must be a map")
        actions = transition.get("actions")
        if not isinstance(actions, list):
            raise ValueError(f"{kind} transition actions must be a list")
        timestamp_ms = transition.get("client_ts_ms")
        if timestamp_ms is not None:
            timestamp_ms = int(timestamp_ms)
        result.append(
            ControlStateTransition(
                payload=normalize_state_payload(actions),
                seq_id=event_id,
                timestamp_ms=timestamp_ms,
            )
        )
    return result

View on GitHub (pinned to 0132848349)

Solutions

1. Include payload: {"transitions": [...]} in the event
2. Validate the event JSON against the control-event schema before sending

Example fix

// before
{"type": "control", "payload": {"state": "on"}}
// after
{"type": "control", "payload": {"transitions": [{"actions": ["mute"], "client_ts_ms": 123}]}}

assert isinstance(event.get("payload", {}).get("transitions"), list), "transitions must be a list"

def has_valid_transitions(payload: dict) -> bool:
    return isinstance(payload.get("transitions"), list)

When it happens

Trigger: parse_control_event_payload receiving an event whose payload has no 'transitions' key, has transitions=null, or transitions as a dict/string.

Common situations: Client sending a malformed control event; schema drift between client and server on the realtime control protocol; JSON built with the wrong payload key ('states' instead of 'transitions').

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

• {kind} transition must be a map
• {path}.kind must be a non-empty string
• {kind} transition actions must be a list
• Feature attrs ({_mm_feature_attrs[modality]}) not found in {
• v_cache must be provided

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