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 extra_config

What it means

When Mooncake config is supplied via the extra_config dict (e.g. from --storage-extra-config), it must contain master_server_address or client_server_address. Neither key was present, so load_from_extra_config() raises ValueError.

Source

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

            device_name=envs.MOONCAKE_DEVICE.get(),
            master_server_address=envs.MOONCAKE_MASTER.get(),
            master_metrics_port=envs.MOONCAKE_MASTER_METRICS_PORT.get(),
            check_server=envs.MOONCAKE_CHECK_SERVER.get(),
            standalone_storage=envs.MOONCAKE_STANDALONE_STORAGE.get(),
            client_server_address=envs.MOONCAKE_CLIENT.get(),
            enable_ssd_offload=envs.MOONCAKE_ENABLE_SSD_OFFLOAD.get(),
            ssd_offload_path=envs.MOONCAKE_OFFLOAD_FILE_STORAGE_PATH.get(),
            tenant_id=_normalize_tenant_id(envs.MOONCAKE_TENANT_ID.get()),
        )

    @staticmethod
    def load_from_extra_config(extra_config: dict) -> "MooncakeStoreConfig":
        """Load config from extra_config dictionary."""
        if (
            "master_server_address" not in extra_config
            and "client_server_address" not in extra_config
        ):
            raise ValueError(
                "Either master_server_address or client_server_address is required in extra_config"
            )

        return MooncakeStoreConfig(
            local_hostname=extra_config.get(
                "local_hostname", envs.MOONCAKE_LOCAL_HOSTNAME.default
            ),
            metadata_server=extra_config.get(
                "metadata_server", envs.MOONCAKE_TE_META_DATA_SERVER.default
            ),
            global_segment_size=_parse_global_segment_size(
                extra_config.get(
                    "global_segment_size", envs.MOONCAKE_GLOBAL_SEGMENT_SIZE.default
                )
            ),
            protocol=extra_config.get("protocol", envs.MOONCAKE_PROTOCOL.default),
            device_name=extra_config.get("device_name", envs.MOONCAKE_DEVICE.default),
            master_server_address=extra_config.get(

View on GitHub (pinned to 0132848349)

Solutions

1. Add master_server_address (or client_server_address) to the extra_config dict/JSON passed via --storage-extra-config

Example fix

# before
--hicache-storage-backend mooncake --storage-extra-config '{"protocol":"tcp"}'
# after
--hicache-storage-backend mooncake --storage-extra-config '{"protocol":"tcp","master_server_address":"10.0.0.2:50051"}'

def extra_config_ok(ec: dict) -> bool:
    return 'master_server_address' in ec or 'client_server_address' in ec
assert extra_config_ok(json.loads(args.storage_extra_config))

When it happens

Trigger: Passing --storage-extra-config '{"protocol":"tcp"}' (only optional keys) when using the mooncake backend.

Common situations: Users forward server kwargs to extra_config but omit the master address; JSON quoting issues silently dropping the key.

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/4b9629ea44ee9ca3. Report an issue: GitHub.