{"record":{"id":"3a5b1cccb86870fe","repo":"sgl-project/sglang","slug":"missing-required-keys-in-config-missing-keys","errorCode":null,"errorMessage":"Missing required keys in config: {missing_keys}","messagePattern":"Missing required keys in config: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/storage/hf3fs/storage_hf3fs.py","lineNumber":342,"sourceCode":"                use_mock_client=use_mock_client,\n            )\n\n        try:\n            with open(config_path, \"r\") as f:\n                config = json.load(f)\n        except Exception as e:\n            raise RuntimeError(f\"Failed to load config from {config_path}: {str(e)}\")\n\n        # Check required keys (metadata_server_url is now optional)\n        required_keys = {\n            \"file_path_prefix\",\n            \"file_size\",\n            \"numjobs\",\n            \"entries\",\n        }\n        missing_keys = required_keys - set(config.keys())\n        if missing_keys:\n            raise ValueError(f\"Missing required keys in config: {missing_keys}\")\n\n        # Choose metadata client based on configuration\n        if config.get(\"metadata_server_url\"):\n            # Use global metadata client to connect to metadata server\n            metadata_server_url = config[\"metadata_server_url\"]\n            metadata_client = Hf3fsGlobalMetadataClient(metadata_server_url)\n\n            logger.info(\n                f\"Using global metadata client with server url: {metadata_server_url}\"\n            )\n        else:\n            # Enable MLA optimization only when using the global metadata client\n            if is_mla_model:\n                raise ValueError(mla_unsupported_msg)\n\n            # Use local metadata client for single-machine deployment\n            metadata_client = Hf3fsLocalMetadataClient()\n","sourceCodeStart":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/storage/hf3fs/storage_hf3fs.py#L324-L360","documentation":"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.","triggerScenarios":"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.","commonSituations":"Upgrading SGLang where the config schema gained a required key; hand-written minimal config; config generator template out of date.","solutions":["Add the missing keys listed in the error to the JSON; fetch entries/file_size from your 3FS deployment sizing","Diff your config against the documented example in the hf3fs docs directory for your SGLang version","Add a startup preflight that validates required keys before launching servers"],"exampleFix":"// before\n{\"file_path_prefix\": \"/data/hicache\", \"file_size\": 1099511627776}\n\n// after\n{\"file_path_prefix\": \"/data/hicache\", \"file_size\": 1099511627776, \"numjobs\": 16, \"entries\": 8388608}","handlingStrategy":"validation","validationCode":"REQUIRED = {'file_path_prefix', 'file_size', 'numjobs', 'entries'}\nmissing = REQUIRED - set(config.keys())\nassert not missing, f'3FS config missing: {missing}'\nbackend = HiCacheHF3FS.from_env_config(rank=rank)","typeGuard":"def is_valid_hf3fs_config(cfg: dict) -> bool:\n    return {'file_path_prefix', 'file_size', 'numjobs', 'entries'} <= set(cfg)","tryCatchPattern":"try:\n    backend = HiCacheHF3FS.from_env_config(rank=rank)\nexcept ValueError as e:\n    if 'Missing required keys' in str(e):\n        fill_defaults_from_template(config_path)\n        backend = HiCacheHF3FS.from_env_config(rank=rank)\n    else:\n        raise","preventionTips":["Generate the config from a versioned template in the repo rather than hand-editing","Add a schema check step to deployment pipelines"],"tags":["hf3fs","config-validation","missing-keys"],"backgroundTag":"config-missing-required-field","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}