{"record":{"id":"d27c8e5fe5e4309a","repo":"sgl-project/sglang","slug":"control-signal-kind-item-kind-r-does-not-match-q","errorCode":null,"errorMessage":"control signal kind {item.kind!r} does not match queue kind {kind!r}","messagePattern":"control signal kind (.+?) does not match queue kind (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/realtime/control_signals.py","lineNumber":292,"sourceCode":"\n    def _iter_signals(\n        self,\n        kind: str,\n        payload: Any,\n        *,\n        event_id: int | None,\n        timestamp_ms: int | None,\n        expand_payload: bool,\n    ):\n        items = (\n            payload\n            if self._should_expand_payload(payload, expand_payload)\n            else (payload,)\n        )\n        for item in items:\n            if isinstance(item, ControlSignal):\n                if item.kind != kind:\n                    raise ValueError(\n                        \"control signal kind \"\n                        f\"{item.kind!r} does not match queue kind {kind!r}\"\n                    )\n                yield item\n            else:\n                yield ControlSignal(\n                    kind=kind,\n                    payload=item,\n                    timestamp_ms=timestamp_ms,\n                    seq_id=event_id,\n                )\n\n    @staticmethod\n    def _should_expand_payload(payload: Any, expand_payload: bool) -> bool:\n        return (\n            expand_payload\n            and isinstance(payload, Sequence)\n            and not isinstance(payload, (str, bytes, bytearray))","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/realtime/control_signals.py#L274-L310","documentation":"A control-signal queue is typed to one signal kind; when push() expands a payload into signals, any ControlSignal whose kind differs from the queue's kind is rejected. This keeps per-kind queues homogeneous so consumers can assume the kind.","triggerScenarios":"Calling queue.push(payload, expand_payload=True) (or plain push of a ControlSignal) where the expanded/inserted ControlSignal.kind != the kind the queue was constructed with.","commonSituations":"Payload expansion (e.g. a state payload that fans out into multiple signal kinds) producing a signal of a different kind; refactoring kinds or adding a new kind and routing it to the wrong queue; reusing a queue across kinds.","solutions":["Inspect the expanded items: ensure the payload only expands into signals of the queue's kind, or split the payload per kind and push to the matching queues.","If a mixed-kind queue is intended, change the queue construction/typing to accept the union of kinds instead of pushing mismatched signals.","Fix the kind string on the producer side (typo/case difference like 'input_audio' vs 'InputAudio')."],"exampleFix":"// before\nqueue = ControlSignalQueue(kind=ControlSignalKind.INTERRUPT)\nqueue.push(state_payload)  # expands into a 'commit' signal -> ValueError\n// after\nfor signal in expand(state_payload):\n    queues[signal.kind].push(signal)","handlingStrategy":"validation","validationCode":"for sig in expand_signals(payload):\n    assert sig.kind == queue.kind, f'route {sig.kind} to its own queue'","typeGuard":"def matches_queue_kind(signal, queue) -> bool:\n    return signal.kind == queue.kind","tryCatchPattern":"try:\n    queue.push(payload)\nexcept ValueError as e:\n    if 'does not match queue kind' in str(e):\n        route_signals_individually(payload)","preventionTips":["Keep a dict of queues keyed by kind and always push expanded signals to queues[sig.kind].","Never push raw expandable payloads into a single-kind queue unless expansion is kind-stable."],"tags":["control-signals","queue","type-mismatch"],"backgroundTag":"invalid-argument-type","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}