sgl-project/sglang · error · RuntimeError

Config file path not set. Please set {envs.SGLANG_HICACHE_MO

Error message

Config file path not set. Please set {envs.SGLANG_HICACHE_MOONCAKE_CONFIG_PATH.name}

What it means

MooncakeStoreConfig.from_file() was invoked but the SGLANG_HICACHE_MOONCAKE_CONFIG_PATH environment variable is unset, so there is no JSON config file to load. The error names the exact variable expected.

Source

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

    local_hostname: str
    metadata_server: str
    global_segment_size: int
    protocol: str
    device_name: str
    master_server_address: str
    master_metrics_port: int
    check_server: bool
    standalone_storage: bool
    client_server_address: str
    enable_ssd_offload: bool = False
    ssd_offload_path: Optional[str] = None
    tenant_id: str = DEFAULT_TENANT_ID

    @staticmethod
    def from_file() -> "MooncakeStoreConfig":
        """Load the config from a JSON file."""
        if not envs.SGLANG_HICACHE_MOONCAKE_CONFIG_PATH.is_set():
            raise RuntimeError(
                f"Config file path not set. Please set {envs.SGLANG_HICACHE_MOONCAKE_CONFIG_PATH.name}"
            )
        file_path = envs.SGLANG_HICACHE_MOONCAKE_CONFIG_PATH.get()
        try:
            with open(file_path) as fin:
                config = json.load(fin)
        except Exception as e:
            raise RuntimeError(f"Failed to load config from {file_path}: {str(e)}")

        if (
            "master_server_address" not in config
            and "client_server_address" not in config
        ):
            raise ValueError(
                "Either master_server_address or client_server_address is required in config file"
            )

        return MooncakeStoreConfig(

View on GitHub (pinned to 0132848349)

Solutions

1. export SGLANG_HICACHE_MOONCAKE_CONFIG_PATH=/path/to/config.json and ensure the file exists
2. Or switch config source to env (MOONCAKE_MASTER/MOONCAKE_CLIENT) or extra_config so from_file is not used

Example fix

# before
python -m sglang.launch_server --hicache-storage-backend mooncake
# after
export SGLANG_HICACHE_MOONCAKE_CONFIG_PATH=/etc/sglang/mooncake.json
python -m sglang.launch_server --hicache-storage-backend mooncake

from sglang.srt import environ as envs
import os
if envs.SGLANG_HICACHE_MOONCAKE_CONFIG_PATH.is_set():
    p = envs.SGLANG_HICACHE_MOONCAKE_CONFIG_PATH.get()
    assert os.path.isfile(p), f'{p} missing'
else:
    # fallback: env-based config requires MOONCAKE_MASTER/MOONCAKE_CLIENT
    assert os.environ.get('MOONCAKE_MASTER') or os.environ.get('MOONCAKE_CLIENT')

try:
    cfg = MooncakeStoreConfig.from_file()
except RuntimeError as e:
    if 'Config file path not set' in str(e):
        os.environ['SGLANG_HICACHE_MOONCAKE_CONFIG_PATH'] = '/etc/sglang/mooncake.json'
        cfg = MooncakeStoreConfig.from_file()
    else:
        raise

When it happens

Trigger: Running with mooncake-backed HiCache where the loader path is 'file' but SGLANG_HICACHE_MOONCAKE_CONFIG_PATH was never exported, or exported in a different shell than the server.

Common situations: Kubernetes/docker env vars dropped; CI script forgot to export; users following mooncache docs that only set MOONCAKE_* vars.

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

• Either the environment variable 'MOONCAKE_MASTER' or 'MOONCA
• File {normalized_input} does not exist.
• Failed to parse JSON content from file {normalized_input}
• Failed to read JSON file {normalized_input}: {exc}
• Invalid JSON mapping: {normalized_input}

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