{"record":{"id":"44bce04ee3b8a64d","repo":"sgl-project/sglang","slug":"mooncake-encoder-transfer-backend-requires-http-en","errorCode":null,"errorMessage":"mooncake encoder_transfer_backend requires HTTP encoders; use zmq_to_scheduler / zmq_to_tokenizer with gRPC.","messagePattern":"mooncake encoder_transfer_backend requires HTTP encoders; use zmq_to_scheduler / zmq_to_tokenizer with gRPC\\.","errorType":"validation","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/encoder/receiver.py","lineNumber":2538,"sourceCode":"            )\n\n\nclass MMReceiverGrpc(MMReceiverBase):\n    def __init__(\n        self,\n        server_args: ServerArgs,\n        dtype: Optional[torch.dtype] = None,\n        hf_config: Optional[PretrainedConfig] = None,\n        pp_rank: Optional[int] = None,\n        tp_rank: Optional[int] = None,\n        tp_group: Optional[GroupCoordinator] = None,\n        scheduler: Optional[\"Scheduler\"] = None,\n        encode_urls: Optional[List[str]] = None,\n    ):\n        if get_disagg().encoder_transfer_backend == \"mooncake\":\n            # The RDMA receive path (WaitingRDMARequest + /meta + /send) only\n            # exists for HTTP encoders; gRPC has no RDMA-capable receive.\n            raise NotImplementedError(\n                \"mooncake encoder_transfer_backend requires HTTP encoders; \"\n                \"use zmq_to_scheduler / zmq_to_tokenizer with gRPC.\"\n            )\n        super().__init__(\n            server_args,\n            dtype=dtype,\n            hf_config=hf_config,\n            pp_rank=pp_rank,\n            tp_rank=tp_rank,\n            tp_group=tp_group,\n            scheduler=scheduler,\n            encode_urls=encode_urls,\n        )\n\n    # For zmq_to_scheduler\n    def process_waiting_requests(self, recv_reqs):\n        return self._process_waiting_requests(recv_reqs, WaitingZmqRequestGrpc)\n","sourceCodeStart":2520,"sourceCodeEnd":2556,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/encoder/receiver.py#L2520-L2556","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\n--disaggregation-encoder-transfer-backend mooncake\nSGLANG_ENCODER_MM_RECEIVER_MODE=grpc\n# after\n--disaggregation-encoder-transfer-backend mooncake\n# encoder urls stay http:// ...; unset SGLANG_ENCODER_MM_RECEIVER_MODE","handlingStrategy":"validation","validationCode":"from sglang.srt.disaggregation.utils import get_disagg  # adjust import as needed\n\nassert not (\n    get_disagg().encoder_transfer_backend == \"mooncake\"\n    and receiver_mode == \"grpc\"\n), \"mooncake transfer requires HTTP encoders; unset SGLANG_ENCODER_MM_RECEIVER_MODE\"","typeGuard":null,"tryCatchPattern":"try:\n    receiver = MMReceiverGrpc(...)\nexcept NotImplementedError as e:\n    raise SystemExit(f\"config conflict: {e}\") from e","preventionTips":["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."],"tags":["mooncake","rdma","grpc","disaggregation","configuration","epd"],"backgroundTag":"incompatible-config-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}