sgl-project/sglang · error · ValueError

Either master_server_address or client_server_address is req

Error message

Either master_server_address or client_server_address is required in config file

What it means

The parsed mooncake JSON config contains neither master_server_address nor client_server_address, but at least one is mandatory to locate the transfer-engine metadata service. This is a semantic validation right after successful JSON parsing.

Source

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

    @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(
            local_hostname=config.get(
                "local_hostname", envs.MOONCAKE_LOCAL_HOSTNAME.default
            ),
            metadata_server=config.get(
                "metadata_server", envs.MOONCAKE_TE_META_DATA_SERVER.default
            ),
            global_segment_size=_parse_global_segment_size(
                config.get(
                    "global_segment_size", envs.MOONCAKE_GLOBAL_SEGMENT_SIZE.default
                )
            ),
            protocol=config.get("protocol", envs.MOONCAKE_PROTOCOL.default),
            device_name=config.get("device_name", envs.MOONCAKE_DEVICE.default),
            master_server_address=config.get(

View on GitHub (pinned to 0132848349)

Solutions

1. Add "master_server_address": "ip:port" (or client_server_address) to the JSON

Example fix

// before
{"local_hostname": "10.0.0.1"}
// after
{"local_hostname": "10.0.0.1", "master_server_address": "10.0.0.2:2379"}

def mooncake_config_has_server(cfg: dict) -> bool:
    return 'master_server_address' in cfg or 'client_server_address' in cfg
assert mooncake_config_has_server(json.load(open(path)))

When it happens

Trigger: A config JSON with only optional keys (local_hostname, protocol, device_name, ...) and no master/client server address.

Common situations: Copied a partial example config; renamed key incorrectly (e.g. master_address).

Related errors

• Either master_server_address or client_server_address is req
• Invalid global_segment_size: missing number before 'gb'
• Invalid threshold_type for topk: {threshold_type}. Choose 'q
• Invalid threshold_type: {threshold_type}. Choose 'query_head
• f"Unknown feature map: {feature_map}"

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