What causes "Unknown request_id: {request_id}" in sgl-project/sglang?

Guard handlers: look up the record (or catch this ValueError) and drop/log late frames for unknown ids instead of propagating

sgl-project/sglang · error · ValueError

Unknown request_id: {request_id}

Error message

Unknown request_id: {request_id}

What it means

Raised by RequestStateStore.transition when the given request_id has no record in the store. All state transitions (dispatch, transfer staged, completion, failure) operate on a previously submitted RequestRecord, so an unknown id indicates the request was never submitted, was already cleaned up, or the id is wrong.

Source

Thrown at python/sglang/multimodal_gen/runtime/disaggregation/request_state.py:104

                raise ValueError(f"Duplicate request_id: {request_id}")
            record = RequestRecord(request_id=request_id)
            self._requests[request_id] = record
            return record

    def transition(
        self,
        request_id: str,
        new_state: RequestState,
        *,
        error: str | None = None,
        encoder_instance: int | None = None,
        denoiser_instance: int | None = None,
        decoder_instance: int | None = None,
    ) -> RequestRecord:
        with self._lock:
            record = self._requests.get(request_id)
            if record is None:
                raise ValueError(f"Unknown request_id: {request_id}")

            old_state = record.state

            if new_state in _TERMINAL_STATES and new_state != RequestState.DONE:
                # FAILED / TIMED_OUT: allowed from any active state
                if old_state not in _ACTIVE_STATES:
                    raise ValueError(
                        f"Cannot transition {request_id} from terminal state "
                        f"{old_state.value} to {new_state.value}"
                    )
            elif new_state not in _VALID_TRANSITIONS.get(old_state, set()):
                raise ValueError(
                    f"Invalid transition for {request_id}: "
                    f"{old_state.value} -> {new_state.value}"
                )

            record.state = new_state
            record.last_transition_time = time.monotonic()

View on GitHub (pinned to 0132848349)

Solutions

Guard handlers: look up the record (or catch this ValueError) and drop/log late frames for unknown ids instead of propagating
Ensure the request is submit()ted before any component can emit frames referencing its id
Delay or cancel in-flight work (encoder/decoder/transfer tasks) before removing terminal requests from the store
On restart, reset clients/queues so stale ids are not reused against an empty store

Example fix

# before
store.transition(request_id, RequestState.DECODING)  # ValueError if unknown

# after
try:
    store.transition(request_id, RequestState.DECODING)
except ValueError:
    logger.warning("dropping frame for unknown request %s", request_id)
    return

Defensive patterns

Strategy: try-catch

Validate before calling

record = store.get(request_id) if hasattr(store, "get") else None
if record is None:
    # unknown/already-cleaned request; drop or re-submit
    logger.warning("unknown request %s; ignoring frame", request_id)
    return

Try / catch

try:
    store.transition(request_id, new_state)
except ValueError as e:
    if "Unknown request_id" in str(e):
        logger.debug("late frame for cleaned request %s", request_id)
        return  # idempotent drop
    raise

Prevention

Submit() the request before subscribing any handler that can emit frames for it
Delay store cleanup of terminal requests until in-flight frames are drained or cancelled
Log request ids end-to-end so unknown-id frames can be traced to races or restarts

When it happens

Trigger: Calling transition(request_id, ...) from any handler (_handle_client_request, _handle_decoder_result_frames, _dispatch_to_encoder, _complete_with_error, _handle_transfer_staged, _transfer_dispatch_to_denoiser) for an id that was never submit()ted or was evicted after reaching a terminal state.

Common situations: Frames arriving after a request completed and was removed from the store (race between completion and late decoder frames), restarts that lose in-memory state while clients keep sending, id mismatches between encode/decode stages, or processing an error for an already-cleaned request.

Related errors

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