{"record":{"id":"3f3c370634ad0e9e","repo":"hiyouga/LlamaFactory","slug":"deepspeed-config-file-is-required-in-dist-config-3f3c37","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/trainer_plugins/distributed/deepspeed.py","lineNumber":60,"sourceCode":"}\n\n\nclass DeepSpeedEngine:\n    \"\"\"DeepSpeed integration using accelerate's built-in capabilities.\n\n    This replaces the manual DeepSpeedConfigHelper / DeepSpeedEngine approach\n    with accelerate's Accelerator + DeepSpeedPlugin, which handles:\n    - Config syncing (auto values, batch size, lr, etc.)\n    - deepspeed.initialize() call\n    - Optimizer / LR scheduler wrapping\n    - Backward + gradient accumulation boundary\n    - ZeRO-3 parameter gathering for saving\n    \"\"\"\n\n    def __init__(self, dist_config: dict[str, Any], num_micro_batch: int = 1, micro_batch_size: int = 1):\n        config_file = dist_config.get(\"config_file\")\n        if not config_file:\n            raise ValueError(\"DeepSpeed config_file is required in dist_config\")\n\n        ds_plugin = DeepSpeedPlugin(hf_ds_config=config_file)\n        ds_plugin.set_mixed_precision(infer_deepspeed_mixed_precision(ds_plugin.deepspeed_config))\n\n        self.accelerator = Accelerator(\n            deepspeed_plugin=ds_plugin,\n            gradient_accumulation_steps=num_micro_batch,\n        )\n\n        # Resolve \"auto\" for train_micro_batch_size_per_gpu so that\n        # accelerate.prepare() does not require a DataLoader to infer it.\n        ds_config = self.accelerator.state.deepspeed_plugin.deepspeed_config\n        if ds_config.get(\"train_micro_batch_size_per_gpu\") in (None, \"auto\"):\n            ds_config[\"train_micro_batch_size_per_gpu\"] = micro_batch_size\n\n        logger.info_rank0(f\"DeepSpeedEngine initialized with config: {config_file}\")\n\n    def shard_model(self, model: HFModel) -> \"DeepSpeedEngine\":","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/plugins/trainer_plugins/distributed/deepspeed.py#L42-L78","documentation":"The v1 DeepSpeed plugin wraps accelerate's DeepSpeedPlugin, which requires a DeepSpeed JSON config file. The wrapper reads dist_config['config_file'] and aborts if missing or empty, because accelerate cannot construct the plugin without it. Inline dict configs are not accepted by this wrapper.","triggerScenarios":"Initializing the DeepSpeed distributed backend with a dist_config dict that has no 'config_file' key, or where config_file is an empty string / None.","commonSituations":"User writes ds_config settings inline in dist_config instead of referencing a ds_z2_config.json file; path variable resolves to empty string due to env or YAML interpolation; migrating from v0 where config was resolved differently.","solutions":["Create a DeepSpeed JSON config (e.g. examples/deepspeed/ds_z2_config.json) and set dist_config['config_file'] to its path","Verify the path exists and is readable before launching","Do not pass the DeepSpeed settings as an inline dict; only the file reference is supported here"],"exampleFix":"# before\ndist_config = {\"zero_stage\": 2}\n\n# after\ndist_config = {\"config_file\": \"examples/deepspeed/ds_z2_config.json\"}","handlingStrategy":"validation","validationCode":"cfg_file = dist_config.get(\"config_file\")\nassert cfg_file and os.path.isfile(cfg_file), f\"dist_config.config_file must reference an existing DeepSpeed JSON, got {cfg_file!r}\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always reference a checked-in ds_*.json config file","Fail fast on missing config_file in launcher scripts before torchrun spawns workers"],"tags":["deepspeed","distributed","configuration"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}