sgl-project/sglang · error · ValueError

EPD MMReceiver: http mode requires http:// encoder URLs. Set

Error message

EPD MMReceiver: http mode requires http:// encoder URLs. Set SGLANG_ENCODER_MM_RECEIVER_MODE=grpc for grpc:// URLs.

What it means

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.

Source

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

def _validate_transport_mode(transport_mode: str, encoder_urls):
    if transport_mode == "grpc":
        invalid_prefix = "http://"
        error_msg = (
            "EPD MMReceiver: grpc mode requires grpc:// encoder URLs. "
            "Set SGLANG_ENCODER_MM_RECEIVER_MODE=http for http:// URLs."
        )
    elif transport_mode == "http":
        invalid_prefix = "grpc://"
        error_msg = (
            "EPD MMReceiver: http mode requires http:// encoder URLs. "
            "Set SGLANG_ENCODER_MM_RECEIVER_MODE=grpc for grpc:// URLs."
        )
    else:
        return

    if any(url.startswith(invalid_prefix) for url in encoder_urls):
        raise ValueError(error_msg)


_MM_RECEIVER_BY_MODE = {
    "grpc": MMReceiverGrpc,
    "http": MMReceiverHTTP,
}


def create_mm_receiver(
    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,
    transport_mode: Optional[str] = None,
    encode_urls: Optional[List[str]] = None,

View on GitHub (pinned to 0132848349)

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).

Example fix

# before
SGLANG_ENCODER_MM_RECEIVER_MODE=http
--encoder-urls grpc://enc0:9000
# after
SGLANG_ENCODER_MM_RECEIVER_MODE=grpc
--encoder-urls grpc://enc0:9000

Defensive patterns

Strategy: validation

Validate before calling

import os

mode = os.environ.get("SGLANG_ENCODER_MM_RECEIVER_MODE", "http")
invalid = "grpc://" if mode == "http" else "http://"
bad = [u for u in (encode_urls or []) if u.startswith(invalid)]
assert not bad, f"{mode} receiver mode rejects {invalid} urls: {bad}"

Try / catch

try:
    receiver = create_mm_receiver(...)
except ValueError as e:
    raise SystemExit(f"encoder URL scheme / receiver mode mismatch: {e}") from e

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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