Lightning-AI/pytorch-lightning · critical · MisconfigurationException

To use DeepSpeed you must pass in a DeepSpeed config dict, o

Error message

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

What it means

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.

Source

Thrown at src/lightning/pytorch/strategies/deepspeed.py:833

            config = os.environ[self.DEEPSPEED_ENV_VAR]
        if isinstance(config, (str, Path)):
            if not os.path.isfile(config):
                raise MisconfigurationException(
                    f"You passed in a path to a DeepSpeed config but the path does not exist: {config}"
                )
            with open(config) as f:
                config = json.load(f)
        assert isinstance(config, dict) or config is None
        return config

    def _init_config_if_needed(self) -> None:
        if not self._config_initialized:
            self._format_config()
            self._config_initialized = True

    def _format_config(self) -> None:
        if self.config is None:
            raise MisconfigurationException(
                "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"
            )
        self._format_batch_size_and_grad_accum_config()
        _format_precision_config(
            config=self.config,
            precision=self.precision_plugin.precision,
            loss_scale=self.loss_scale,
            loss_scale_window=self.loss_scale_window,
            min_loss_scale=self.min_loss_scale,
            initial_scale_power=self.initial_scale_power,
            hysteresis=self.hysteresis,
        )

    def _create_default_config(
        self,
        zero_optimization: bool,
        zero_allow_untested_optimizer: bool,

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Pass a config: `DeepSpeedStrategy(config={"zero_optimization": {...}, "train_micro_batch_size_per_gpu": ...})`
2. Or export the documented environment variable with a path to your JSON config before constructing the Trainer
3. Start from Lightning's minimal DeepSpeed config examples in the model_parallel docs

Example fix

# before
strategy = DeepSpeedStrategy()

# after
strategy = DeepSpeedStrategy(config={
    "train_micro_batch_size_per_gpu": 8,
    "zero_optimization": {"stage": 2},
})

ds_config = {"train_micro_batch_size_per_gpu": 8, "zero_optimization": {"stage": 2}}
strategy = DeepSpeedStrategy(config=ds_config)

When it happens

Trigger: `DeepSpeedStrategy()` without `config`, without the environment variable set, and without remote/env-provided config, then starting training (the config is lazily formatted in setup).

Common situations: 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.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• No models were set up for backward. Did you forget to call `
• When using multiple models + deepspeed, please provide the m
• The `{type(self._strategy).__name__}` requires the model and
• `precision={precision!r})` is not supported in DeepSpeed. `p
• To use the `DeepSpeedStrategy`, you must have DeepSpeed inst

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/0f1abf55b8731194. Report an issue: GitHub.