What causes "Failed to load config from {config_path}: {str(e)}" in sgl-project/sglang?

Validate the file exists and parses: python -c "import json;json.load(open('/path/config.json'))"

sgl-project/sglang · error · RuntimeError

Failed to load config from {config_path}: {str(e)}

Error message

Failed to load config from {config_path}: {str(e)}

What it means

from_env_config opens the JSON file named by the env var and json.load's it; any exception (file missing, permission denied, invalid JSON, BOM/encoding issue) is re-raised as RuntimeError with the path and original message.

Source

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

            return HiCacheHF3FS(
                rank=rank,
                file_path=f"/data/hicache.{rank}.bin",
                file_size=1 << 40,
                numjobs=16,
                bytes_per_page=bytes_per_page,
                entries=8,
                client_timeout=5,
                dtype=dtype,
                metadata_client=Hf3fsLocalMetadataClient(),
                is_page_first_layout=is_page_first_layout,
                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)

View on GitHub (pinned to 0132848349)

Solutions

Validate the file exists and parses: python -c "import json;json.load(open('/path/config.json'))"
Use an absolute path for the env var value and verify mount/permissions in the container
Re-serde the JSON from a known-good template to eliminate syntax errors

Defensive patterns

Strategy: validation

Validate before calling

import json, os

path = os.getenv(env_var)
assert path and os.path.isfile(path), f'missing config file: {path}'
config = json.load(open(path))  # raises here with a clear JSON error, not at from_env_config

Try / catch

try:
    backend = HiCacheHF3FS.from_env_config(rank=rank)
except RuntimeError as e:
    if 'Failed to load config' in str(e):
        raise SystemExit(f'fix 3FS config file: {e}')
    raise

Prevention

Validate the JSON with python -m json.tool in CI/deploy scripts
Use absolute paths and mount the config via a configmap/secret so it is always present

When it happens

Trigger: Setting the HF3FS config env var to a nonexistent path, a path with wrong permissions, or a file containing malformed JSON (trailing commas, comments, single quotes).

Common situations: Helm/K8s secret not mounted at the configured path; JSON hand-edited and broken; relative path resolved against a different working directory in a container.

Related errors

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