sgl-project/sglang · error · ValueError

Either the environment variable 'MOONCAKE_MASTER' or 'MOONCA

Error message

Either the environment variable 'MOONCAKE_MASTER' or 'MOONCAKE_CLIENT' is not set.

What it means

Env-based Mooncake config loading requires MOONCAKE_MASTER or MOONCAKE_CLIENT to identify the metadata service; neither is set, so load_from_env() raises ValueError. The docstring above it shows the full expected env set (MOONCAKE_PROTOCOL, MOONCAKE_DEVICE, MOONCAKE_TE_META_DATA_SERVER, ...).

Source

Thrown at python/sglang/srt/mem_cache/storage/mooncake_store/mooncake_store.py:179

            ssd_offload_path=config.get(
                "ssd_offload_path", envs.MOONCAKE_OFFLOAD_FILE_STORAGE_PATH.default
            ),
            tenant_id=_normalize_tenant_id(
                config.get("tenant_id", envs.MOONCAKE_TENANT_ID.default)
            ),
        )

    @staticmethod
    def load_from_env() -> "MooncakeStoreConfig":
        """Load config from a file specified in the environment variable.
        export MOONCAKE_MASTER=10.13.3.232:50051
        export MOONCAKE_PROTOCOL="rdma"
        export MOONCAKE_DEVICE=""
        export MOONCAKE_TE_META_DATA_SERVER="P2PHANDSHAKE"
        """
        # other required environment variables...
        if not envs.MOONCAKE_MASTER.is_set() and not envs.MOONCAKE_CLIENT.is_set():
            raise ValueError(
                "Either the environment variable 'MOONCAKE_MASTER' or 'MOONCAKE_CLIENT' is not set."
            )

        # Special handling for local_hostname: try MOONCAKE_LOCAL_HOSTNAME first,
        # then fall back to LOCAL_HOSTNAME if not set.
        # This is for forward compatibility with the legacy LOCAL_HOSTNAME environment variable.
        if envs.MOONCAKE_LOCAL_HOSTNAME.is_set():
            local_hostname = envs.MOONCAKE_LOCAL_HOSTNAME.get()
        else:
            local_hostname = os.getenv(
                "LOCAL_HOSTNAME", envs.MOONCAKE_LOCAL_HOSTNAME.default
            )

        return MooncakeStoreConfig(
            local_hostname=local_hostname,
            metadata_server=envs.MOONCAKE_TE_META_DATA_SERVER.get(),
            global_segment_size=_parse_global_segment_size(
                envs.MOONCAKE_GLOBAL_SEGMENT_SIZE.get()

View on GitHub (pinned to 0132848349)

Solutions

1. export MOONCAKE_MASTER=<ip:port> (or MOONCAKE_CLIENT) plus the documented MOONCAKE_* vars
2. Or provide the JSON config file / extra_config so env loading is skipped

Example fix

# before
python -m sglang.launch_server --hicache-storage-backend mooncake  # no env
# after
export MOONCAKE_MASTER=10.0.0.2:50051
export MOONCAKE_TRANSFER_ENGINE=rdma
python -m sglang.launch_server --hicache-storage-backend mooncake

import os
assert os.environ.get('MOONCAKE_MASTER') or os.environ.get('MOONCAKE_CLIENT'), \
    'set MOONCAKE_MASTER=<ip:port> (or MOONCAKE_CLIENT) before launching SGLang with mooncake'

When it happens

Trigger: Config source resolves to env (no config file, no extra_config) while both MOONCAKE_MASTER and MOONCAKE_CLIENT are unset in the process environment.

Common situations: Launching SGLang with mooncake backend in a fresh shell/CI pod without sourcing the mooncake env script; env vars set only on the master node, not workers.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Config file path not set. Please set {envs.SGLANG_HICACHE_MO
• unknown q-prep variant {variant!r} (SGLANG_OPT_Q8KV8_QPREP_V
• Invalid ltx2_two_stage_device_mode={mode!r}. Expected one of
• --enable-hisparse is not supported with the unified-KV path
• Kimi-K3 DCP + DSPARK currently requires SGLANG_RAGGED_VERIFY

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