sgl-project/sglang · error · ValueError

Missing required keys in config: {missing_keys}

Error message

Missing required keys in config: {missing_keys}

What it means

After loading the config JSON, from_env_config enforces required keys {file_path_prefix, file_size, numjobs, entries} (metadata_server_url is optional). Missing keys raise ValueError listing exactly which are absent.

Source

Thrown at python/sglang/srt/mem_cache/storage/hf3fs/storage_hf3fs.py:342

                use_mock_client=use_mock_client,
            )

        try:
            with open(config_path, "r") as f:
                config = json.load(f)
        except Exception as e:
            raise RuntimeError(f"Failed to load config from {config_path}: {str(e)}")

        # Check required keys (metadata_server_url is now optional)
        required_keys = {
            "file_path_prefix",
            "file_size",
            "numjobs",
            "entries",
        }
        missing_keys = required_keys - set(config.keys())
        if missing_keys:
            raise ValueError(f"Missing required keys in config: {missing_keys}")

        # Choose metadata client based on configuration
        if config.get("metadata_server_url"):
            # Use global metadata client to connect to metadata server
            metadata_server_url = config["metadata_server_url"]
            metadata_client = Hf3fsGlobalMetadataClient(metadata_server_url)

            logger.info(
                f"Using global metadata client with server url: {metadata_server_url}"
            )
        else:
            # Enable MLA optimization only when using the global metadata client
            if is_mla_model:
                raise ValueError(mla_unsupported_msg)

            # Use local metadata client for single-machine deployment
            metadata_client = Hf3fsLocalMetadataClient()

View on GitHub (pinned to 0132848349)

Solutions

1. Add the missing keys listed in the error to the JSON; fetch entries/file_size from your 3FS deployment sizing
2. Diff your config against the documented example in the hf3fs docs directory for your SGLang version
3. Add a startup preflight that validates required keys before launching servers

Example fix

// before
{"file_path_prefix": "/data/hicache", "file_size": 1099511627776}

// after
{"file_path_prefix": "/data/hicache", "file_size": 1099511627776, "numjobs": 16, "entries": 8388608}

REQUIRED = {'file_path_prefix', 'file_size', 'numjobs', 'entries'}
missing = REQUIRED - set(config.keys())
assert not missing, f'3FS config missing: {missing}'
backend = HiCacheHF3FS.from_env_config(rank=rank)

def is_valid_hf3fs_config(cfg: dict) -> bool:
    return {'file_path_prefix', 'file_size', 'numjobs', 'entries'} <= set(cfg)

try:
    backend = HiCacheHF3FS.from_env_config(rank=rank)
except ValueError as e:
    if 'Missing required keys' in str(e):
        fill_defaults_from_template(config_path)
        backend = HiCacheHF3FS.from_env_config(rank=rank)
    else:
        raise

When it happens

Trigger: A config JSON that omits one or more of file_path_prefix/file_size/numjobs/entries — e.g. copied from a partial example or keys renamed during a version upgrade.

Common situations: Upgrading SGLang where the config schema gained a required key; hand-written minimal config; config generator template out of date.

Related errors

• bad compress_ratio {compress_ratio}
• The requested FlashAttention forward configuration exceeds S
• flashinfer_sparse_mla supports only GLM DSA with FP8 KV cach
• GLM DSA with FP8 KV cache on NVIDIA SM120/SM121 supports onl
• kv-canary: RealKvSource.page_size must be >= 1, got {self.pa

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