{"record":{"id":"d3e238d27f51c70e","repo":"hiyouga/LlamaFactory","slug":"deepspeed-config-file-is-required-in-dist-config","errorCode":null,"errorMessage":"DeepSpeed config_file is required in dist_config","messagePattern":"DeepSpeed config_file is required in dist_config","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/v1/plugins/model_plugins/deepspeed_utils.py","lineNumber":100,"sourceCode":"    try:\n        from transformers.integrations import unset_hf_deepspeed_config\n    except ImportError:\n        from transformers.deepspeed import unset_hf_deepspeed_config\n\n    unset_hf_deepspeed_config()\n\n\ndef _load_deepspeed_config(config_file: str) -> dict[str, Any]:\n    with open(config_file, encoding=\"utf-8\") as f:\n        return json.load(f)\n\n\ndef setup_deepspeed_zero3_model_loading():\n    \"\"\"Enable ZeRO-3-aware model loading for the registered backend config.\"\"\"\n    dist_config = _registered_dist_config\n    config_file = dist_config.get(\"config_file\") if dist_config is not None else None\n    if not config_file:\n        raise ValueError(\"DeepSpeed config_file is required in dist_config\")\n\n    from accelerate.utils import DeepSpeedPlugin\n\n    try:\n        from transformers.integrations import is_deepspeed_zero3_enabled as _hf_is_deepspeed_zero3_enabled\n    except ImportError:\n        from transformers.deepspeed import is_deepspeed_zero3_enabled as _hf_is_deepspeed_zero3_enabled\n\n    # DeepSpeed configs often use \"auto\" placeholders that only make sense once\n    # we know the current runtime batch settings and precision mode.\n    ds_config = deepcopy(_load_deepspeed_config(config_file))\n    if \"gradient_accumulation_steps\" not in ds_config or ds_config[\"gradient_accumulation_steps\"] == \"auto\":\n        ds_config[\"gradient_accumulation_steps\"] = 1\n    if \"train_micro_batch_size_per_gpu\" not in ds_config or ds_config[\"train_micro_batch_size_per_gpu\"] == \"auto\":\n        ds_config[\"train_micro_batch_size_per_gpu\"] = 1\n    if ds_config.get(\"train_batch_size\") == \"auto\":\n        ds_config.pop(\"train_batch_size\")\n","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/plugins/model_plugins/deepspeed_utils.py#L82-L118","documentation":"setup_deepspeed_zero3_model_loading() needs the path to a DeepSpeed JSON config to construct the accelerate DeepSpeedPlugin with zero3_init. It reads it from the registered distributed config dict; if config_file is missing, empty, or no dist config was registered at all, it raises this ValueError.","triggerScenarios":"Calling setup_deepspeed_zero3_model_loading() before registering the dist config, or registering a dist config without a 'config_file' key (e.g. only engine/args set programmatically).","commonSituations":"Programmatic use of the v1 API where DeepSpeed is enabled via arguments rather than a YAML that carries deepspeed: path; typos in the config key; forgetting that ZeRO-3 init loading requires an explicit config file.","solutions":["Set the 'config_file' key in the registered dist_config to a valid DeepSpeed JSON path before calling setup.","In YAML configs, point the deepspeed option at the JSON file so registration carries it.","Check the file exists and is readable JSON (a bad path fails later in _load_deepspeed_config).","If you do not want ZeRO-3 init loading, skip calling this function at all."],"exampleFix":"# before\ndist_config = {\"engine\": \"deepspeed\"}  # no config_file\nsetup_deepspeed_zero3_model_loading()\n\n# after\ndist_config = {\"engine\": \"deepspeed\", \"config_file\": \"ds_zero3.json\"}\nsetup_deepspeed_zero3_model_loading()","handlingStrategy":"validation","validationCode":"import os\ncfg_file = dist_config.get('config_file') if dist_config else None\nassert cfg_file and os.path.isfile(cfg_file), 'DeepSpeed config_file missing or not a file'","typeGuard":"def has_deepspeed_config(dist_config: dict | None) -> bool:\n    \"\"\"True when dist_config carries an existing config_file path.\"\"\"\n    f = (dist_config or {}).get('config_file')\n    return bool(f) and os.path.isfile(f)","tryCatchPattern":"try:\n    plugin = setup_deepspeed_zero3_model_loading()\nexcept ValueError as e:\n    if 'config_file is required' in str(e):\n        raise SystemExit('set deepspeed: ds_zero3.json in the YAML') from None\n    raise","preventionTips":["Always reference a DeepSpeed JSON from the training YAML when using ZeRO-3.","Register the dist config before any ZeRO-3 loading helper call.","Unit-test config registration in programmatic setups."],"tags":["deepspeed","config","distributed","zero3"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}