{"record":{"id":"0f1abf55b8731194","repo":"Lightning-AI/pytorch-lightning","slug":"to-use-deepspeed-you-must-pass-in-a-deepspeed-conf-0f1abf","errorCode":null,"errorMessage":"To use DeepSpeed you must pass in a DeepSpeed config dict, or a path to a JSON config. See: https://lightning.ai/docs/pytorch/stable/advanced/model_parallel.html#deepspeed","messagePattern":"To use DeepSpeed you must pass in a DeepSpeed config dict, or a path to a JSON config\\. See: https://lightning\\.ai/docs/pytorch/stable/advanced/model_parallel\\.html#deepspeed","errorType":"exception","errorClass":"MisconfigurationException","httpStatus":null,"severity":"critical","filePath":"src/lightning/pytorch/strategies/deepspeed.py","lineNumber":833,"sourceCode":"            config = os.environ[self.DEEPSPEED_ENV_VAR]\n        if isinstance(config, (str, Path)):\n            if not os.path.isfile(config):\n                raise MisconfigurationException(\n                    f\"You passed in a path to a DeepSpeed config but the path does not exist: {config}\"\n                )\n            with open(config) as f:\n                config = json.load(f)\n        assert isinstance(config, dict) or config is None\n        return config\n\n    def _init_config_if_needed(self) -> None:\n        if not self._config_initialized:\n            self._format_config()\n            self._config_initialized = True\n\n    def _format_config(self) -> None:\n        if self.config is None:\n            raise MisconfigurationException(\n                \"To use DeepSpeed you must pass in a DeepSpeed config dict, or a path to a JSON config.\"\n                \" See: https://lightning.ai/docs/pytorch/stable/advanced/model_parallel.html#deepspeed\"\n            )\n        self._format_batch_size_and_grad_accum_config()\n        _format_precision_config(\n            config=self.config,\n            precision=self.precision_plugin.precision,\n            loss_scale=self.loss_scale,\n            loss_scale_window=self.loss_scale_window,\n            min_loss_scale=self.min_loss_scale,\n            initial_scale_power=self.initial_scale_power,\n            hysteresis=self.hysteresis,\n        )\n\n    def _create_default_config(\n        self,\n        zero_optimization: bool,\n        zero_allow_untested_optimizer: bool,","sourceCodeStart":815,"sourceCodeEnd":851,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/strategies/deepspeed.py#L815-L851","documentation":"DeepSpeed requires a config (dict or JSON path) to build its engine. If neither `config=` was passed nor the DEEPSPEED_ENV_VAR environment variable is set, self.config stays None and _format_config raises MisconfigurationException when the strategy prepares to initialize DeepSpeed.","triggerScenarios":"`DeepSpeedStrategy()` without `config`, without the environment variable set, and without remote/env-provided config, then starting training (the config is lazily formatted in setup).","commonSituations":"Assuming ZeRO is enabled via Trainer flags alone; setting the env var name wrong (it must be the exact DEEPSPEED_ENV_VAR name); passing `config=None` explicitly after refactoring.","solutions":["Pass a config: `DeepSpeedStrategy(config={\"zero_optimization\": {...}, \"train_micro_batch_size_per_gpu\": ...})`","Or export the documented environment variable with a path to your JSON config before constructing the Trainer","Start from Lightning's minimal DeepSpeed config examples in the model_parallel docs"],"exampleFix":"# before\nstrategy = DeepSpeedStrategy()\n\n# after\nstrategy = DeepSpeedStrategy(config={\n    \"train_micro_batch_size_per_gpu\": 8,\n    \"zero_optimization\": {\"stage\": 2},\n})","handlingStrategy":"validation","validationCode":"ds_config = {\"train_micro_batch_size_per_gpu\": 8, \"zero_optimization\": {\"stage\": 2}}\nstrategy = DeepSpeedStrategy(config=ds_config)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass config= (dict or JSON path) when using DeepSpeedStrategy","Or set the DEEPSPEED_ENV_VAR environment variable with a config path"],"tags":["deepspeed","missing-config","zero-optimization"],"backgroundTag":"missing-required-config","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}