Lightning-AI/pytorch-lightning · error · ValueError

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

DeepSpeedStrategy needs a DeepSpeed configuration to initialize the engine. _format_config raises ValueError when self.config is None (no dict, no JSON path, and no DEEPSPEED_ENV_VAR was set), because there is no way to infer all engine settings.

Source

Thrown at src/lightning/fabric/strategies/deepspeed.py:701

        os.environ["LOCAL_RANK"] = str(self.local_rank)

    def _set_deepspeed_activation_checkpointing(self) -> None:
        import deepspeed

        assert isinstance(self.config, dict)
        if self.config.get("activation_checkpointing"):
            checkpoint_config = self.config["activation_checkpointing"]
            deepspeed.checkpointing.configure(
                mpu_=None,
                partition_activations=checkpoint_config.get("partition_activations"),
                contiguous_checkpointing=checkpoint_config.get("contiguous_memory_optimization"),
                checkpoint_in_cpu=checkpoint_config.get("cpu_checkpointing"),
                profile=checkpoint_config.get("profile"),
            )

    def _format_config(self) -> None:
        if self.config is None:
            raise ValueError(
                "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.config.setdefault("train_micro_batch_size_per_gpu", 1)
        _format_precision_config(
            config=self.config,
            precision=self.precision.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,

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Pass a config: DeepSpeedStrategy(config="ds_config.json") or config={...}
2. Or export the environment variable the strategy reads: DEEPSPEED_CONFIG_FILE (check strategy.DEEPSPEED_ENV_VAR) pointing to the JSON file
3. Verify the env var is actually exported in the process running the training (print os.environ)

Example fix

# before
strategy = DeepSpeedStrategy()

# after
strategy = DeepSpeedStrategy(config={"train_batch_size": 8, "optimizer": {"type": "Adam"}})

import os
from lightning.fabric.strategies import DeepSpeedStrategy
if DeepSpeedStrategy.DEEPSPEED_ENV_VAR not in os.environ:
    assert config is not None, "pass DeepSpeedStrategy(config=...) or export the env var"

When it happens

Trigger: Creating DeepSpeedStrategy() with config=None while the DEEPSPEED_ENV_VAR environment variable is unset, then running setup; or Fabric/Trainer automatically selecting the deepspeed strategy without a config on a machine where the env var is absent.

Common situations: Selecting strategy="deepspeed" in the Trainer without passing a config; env-var-based config works in a launcher script but not in an interactive shell/SLURM job where the variable is not exported; typo in the env variable name.

Related errors

• You passed in a path to a DeepSpeed config but the path does
• No models were set up for backward. Did you forget to call `
• When using multiple models + deepspeed, please provide the m
• You have to specify either `clip_val` or `max_norm` to do gr
• The `{type(self._strategy).__name__}` requires the model and

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