Lightning-AI/pytorch-lightning · error · MisconfigurationException

You passed in a path to a DeepSpeed config but the path does

Error message

You passed in a path to a DeepSpeed config but the path does not exist: {config}

What it means

DeepSpeedStrategy accepts a config as either a dict or a path to a JSON file (or via the DEEPSPEED_ENV_VAR env var). _load_config checks the path with os.path.isfile and raises MisconfigurationException if it does not exist, catching typos and wrong relative paths before training.

Source

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

        strategy_registry.register(
            "deepspeed_stage_3_offload_nvme",
            cls,
            description="DeepSpeed ZeRO Stage 3 and NVMe Offload",
            stage=3,
            offload_optimizer=True,
            offload_parameters=True,
            remote_device="nvme",
            offload_params_device="nvme",
            offload_optimizer_device="nvme",
        )

    def _load_config(self, config: Optional[Union[_PATH, dict[str, Any]]]) -> Optional[dict[str, Any]]:
        if config is None and self.DEEPSPEED_ENV_VAR in os.environ:
            rank_zero_info(f"Loading DeepSpeed config from set {self.DEEPSPEED_ENV_VAR} environment variable")
            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"
            )

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Use an absolute path or resolve it relative to the script: `config=Path(__file__).parent / "ds_config.json"`
2. Verify the filename and extension (.json) with `os.path.isfile(config)` before constructing the strategy
3. Or pass the config as a dict directly to avoid filesystem issues

Example fix

# before
strategy = DeepSpeedStrategy(config="configs/ds_zero3.json")  # wrong cwd

# after
from pathlib import Path
strategy = DeepSpeedStrategy(config=Path(__file__).parent / "configs" / "ds_zero3.json")

import os
config_path = "ds_config.json"
if not os.path.isfile(config_path):
    raise FileNotFoundError(f"missing DeepSpeed config: {config_path}")
strategy = DeepSpeedStrategy(config=config_path)

When it happens

Trigger: `DeepSpeedStrategy(config="ds_config.json")` where the string/Path is not an existing file — wrong relative directory, typo, missing file, or a path on another node not present.

Common situations: Running from a different working directory (scripts launched from repo root while config path is relative); launching multi-node jobs where the config was shipped to rank 0 only; `.yaml` config passed where only JSON is supported (path exists check passes only for files — YAML file loads fine as file but json.load then fails; the missing-file case is typo/relative paths).

Related errors

• You passed in a path to a DeepSpeed config but the path does
• Directory '{ds_checkpoint_dir}' doesn't exist
• 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

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