{"record":{"id":"6789ed39d656ec0b","repo":"sgl-project/sglang","slug":"epd-mmreceiver-http-mode-requires-http-encoder","errorCode":null,"errorMessage":"EPD MMReceiver: http mode requires http:// encoder URLs. Set SGLANG_ENCODER_MM_RECEIVER_MODE=grpc for grpc:// URLs.","messagePattern":"EPD MMReceiver: http mode requires http:// encoder URLs\\. Set SGLANG_ENCODER_MM_RECEIVER_MODE=grpc for grpc:// URLs\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/encoder/receiver.py","lineNumber":2645,"sourceCode":"\ndef _validate_transport_mode(transport_mode: str, encoder_urls):\n    if transport_mode == \"grpc\":\n        invalid_prefix = \"http://\"\n        error_msg = (\n            \"EPD MMReceiver: grpc mode requires grpc:// encoder URLs. \"\n            \"Set SGLANG_ENCODER_MM_RECEIVER_MODE=http for http:// URLs.\"\n        )\n    elif transport_mode == \"http\":\n        invalid_prefix = \"grpc://\"\n        error_msg = (\n            \"EPD MMReceiver: http mode requires http:// encoder URLs. \"\n            \"Set SGLANG_ENCODER_MM_RECEIVER_MODE=grpc for grpc:// URLs.\"\n        )\n    else:\n        return\n\n    if any(url.startswith(invalid_prefix) for url in encoder_urls):\n        raise ValueError(error_msg)\n\n\n_MM_RECEIVER_BY_MODE = {\n    \"grpc\": MMReceiverGrpc,\n    \"http\": MMReceiverHTTP,\n}\n\n\ndef create_mm_receiver(\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    transport_mode: Optional[str] = None,\n    encode_urls: Optional[List[str]] = None,","sourceCodeStart":2627,"sourceCodeEnd":2663,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/encoder/receiver.py#L2627-L2663","documentation":"Raised by the EPD MMReceiver transport validation when the receiver is in http mode but one or more encoder URLs start with grpc://. HTTP and gRPC receiver modes each require matching URL schemes, and SGLANG_ENCODER_MM_RECEIVER_MODE selects the mode explicitly.","triggerScenarios":"SGLANG_ENCODER_MM_RECEIVER_MODE=http (or defaulting to http) while encode_urls / encoder_urls contain grpc:// prefixed addresses; e.g. migrating encoder URLs to gRPC without flipping the receiver mode env var.","commonSituations":"Stale env var after switching encoder deployment to gRPC; mixed URL lists where some entries keep the old scheme; copy-pasted configs pairing http mode with grpc endpoints.","solutions":["Set SGLANG_ENCODER_MM_RECEIVER_MODE=grpc when encoder URLs use grpc://.","Or change the encoder URLs to http:// if you intend to keep the http receiver mode.","Audit all entries in encode_urls / --encoder-urls for scheme consistency (the check fails if ANY url has the invalid prefix)."],"exampleFix":"# before\nSGLANG_ENCODER_MM_RECEIVER_MODE=http\n--encoder-urls grpc://enc0:9000\n# after\nSGLANG_ENCODER_MM_RECEIVER_MODE=grpc\n--encoder-urls grpc://enc0:9000","handlingStrategy":"validation","validationCode":"import os\n\nmode = os.environ.get(\"SGLANG_ENCODER_MM_RECEIVER_MODE\", \"http\")\ninvalid = \"grpc://\" if mode == \"http\" else \"http://\"\nbad = [u for u in (encode_urls or []) if u.startswith(invalid)]\nassert not bad, f\"{mode} receiver mode rejects {invalid} urls: {bad}\"","typeGuard":null,"tryCatchPattern":"try:\n    receiver = create_mm_receiver(...)\nexcept ValueError as e:\n    raise SystemExit(f\"encoder URL scheme / receiver mode mismatch: {e}\") from e","preventionTips":["Derive SGLANG_ENCODER_MM_RECEIVER_MODE from the encoder URL scheme in deploy scripts instead of setting it by hand.","Validate all encoder URLs share one scheme at startup.","Re-check the env var after switching encoder deployment between grpc and http."],"tags":["configuration","url-scheme","env-var","grpc","http","epd"],"backgroundTag":"url-scheme-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}