sgl-project/sglang · error · NotImplementedError

mooncake encoder_transfer_backend requires HTTP encoders; us

Error message

mooncake encoder_transfer_backend requires HTTP encoders; use zmq_to_scheduler / zmq_to_tokenizer with gRPC.

What it means

Raised in the gRPC MM receiver constructor when encoder_transfer_backend is set to 'mooncake'. Mooncake's RDMA receive path (WaitingRDMARequest + /meta + /send endpoints) is only implemented for HTTP encoders, so combining mooncake transfer with a gRPC-mode receiver is unsupported.

Source

Thrown at python/sglang/srt/disaggregation/encoder/receiver.py:2538

            )


class MMReceiverGrpc(MMReceiverBase):
    def __init__(
        self,
        server_args: ServerArgs,
        dtype: Optional[torch.dtype] = None,
        hf_config: Optional[PretrainedConfig] = None,
        pp_rank: Optional[int] = None,
        tp_rank: Optional[int] = None,
        tp_group: Optional[GroupCoordinator] = None,
        scheduler: Optional["Scheduler"] = None,
        encode_urls: Optional[List[str]] = None,
    ):
        if get_disagg().encoder_transfer_backend == "mooncake":
            # The RDMA receive path (WaitingRDMARequest + /meta + /send) only
            # exists for HTTP encoders; gRPC has no RDMA-capable receive.
            raise NotImplementedError(
                "mooncake encoder_transfer_backend requires HTTP encoders; "
                "use zmq_to_scheduler / zmq_to_tokenizer with gRPC."
            )
        super().__init__(
            server_args,
            dtype=dtype,
            hf_config=hf_config,
            pp_rank=pp_rank,
            tp_rank=tp_rank,
            tp_group=tp_group,
            scheduler=scheduler,
            encode_urls=encode_urls,
        )

    # For zmq_to_scheduler
    def process_waiting_requests(self, recv_reqs):
        return self._process_waiting_requests(recv_reqs, WaitingZmqRequestGrpc)

View on GitHub (pinned to 0132848349)

Solutions

Use HTTP encoder URLs (zmq_to_scheduler / zmq_to_tokenizer transfer) when mooncake encoder transfer backend is enabled.
Or switch off mooncake: set encoder_transfer_backend to a non-RDMA backend if you must keep grpc:// encoder URLs.
Unset SGLANG_ENCODER_MM_RECEIVER_MODE=grpc so the receiver mode matches HTTP URLs.

Example fix

# before
--disaggregation-encoder-transfer-backend mooncake
SGLANG_ENCODER_MM_RECEIVER_MODE=grpc
# after
--disaggregation-encoder-transfer-backend mooncake
# encoder urls stay http:// ...; unset SGLANG_ENCODER_MM_RECEIVER_MODE

Defensive patterns

Strategy: validation

Validate before calling

from sglang.srt.disaggregation.utils import get_disagg  # adjust import as needed

assert not (
    get_disagg().encoder_transfer_backend == "mooncake"
    and receiver_mode == "grpc"
), "mooncake transfer requires HTTP encoders; unset SGLANG_ENCODER_MM_RECEIVER_MODE"

Try / catch

try:
    receiver = MMReceiverGrpc(...)
except NotImplementedError as e:
    raise SystemExit(f"config conflict: {e}") from e

Prevention

Add a startup config lint: mooncake transfer backend + grpc receiver mode must fail fast with a clear message.
Document that mooncake RDMA transfer pairs only with HTTP encoder URLs.
Keep transfer-backend and receiver-mode settings in one config source to avoid drift.

When it happens

Trigger: Constructing MMReceiverGrpc (e.g. via transport_mode='grpc' or SGLANG_ENCODER_MM_RECEIVER_MODE=grpc) while server disaggregation config sets --disaggregation-encoder-transfer-backend mooncake.

Common situations: Enabling mooncake RDMA transfer for encoder bandwidth but also setting gRPC encoder URLs / receiver mode; copy-pasting a mooncake config into a gRPC-based encoder deployment; upgrading configs where these flags previously were independent.

Related errors

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