Lightning-AI/pytorch-lightning · error · FileNotFoundError

{default_message}. It looks like you passed the path to a su

Error message

{default_message}. It looks like you passed the path to a subfolder. Try to load using this parent directory instead: {parent}

What it means

_validate_checkpoint_directory checks the load path is a real DeepSpeed checkpoint (via _is_deepspeed_checkpoint). If it is not, but the parent directory IS one, the user probably passed the 'checkpoint' subfolder (e.g. .../global_step10/checkpoint) and gets a helpful FileNotFoundError pointing at the parent.

Source

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

    # epoch=5-step=10999.ckpt
    # ├── checkpoint
    # │   ├── zero_pp_rank_0_mp_rank_00_model_states.pt
    # │   ├── zero_pp_rank_0_mp_rank_00_optim_states.pt
    # │   ├── zero_pp_rank_1_mp_rank_00_model_states.pt
    # │   └── zero_pp_rank_1_mp_rank_00_optim_states.pt
    # ├── latest
    # └── zero_to_fp32.py

    path_str = str(path)
    fs = get_filesystem(path_str)
    path_is_ds_checkpoint = _is_deepspeed_checkpoint(path_str, fs)
    default_message = f"The provided path is not a valid DeepSpeed checkpoint: {path_str}"

    if not path_is_ds_checkpoint:
        # Case 1: User may have accidentally passed the subfolder "checkpoint"
        parent = os.path.dirname(path_str)
        if _is_deepspeed_checkpoint(parent, fs):
            raise FileNotFoundError(
                f"{default_message}. It looks like you passed the path to a subfolder."
                f" Try to load using this parent directory instead: {parent}"
            )
        # Case 2: User may have accidentally passed the path to a file inside the "checkpoint" subfolder
        grandparent = os.path.dirname(parent)
        if fs.isfile(path_str) and _is_deepspeed_checkpoint(grandparent, fs):
            raise FileNotFoundError(
                f"{default_message}. It looks like you passed the path to a file inside a DeepSpeed"
                f" checkpoint folder. Try to load using this parent directory instead: {grandparent}"
            )
        raise FileNotFoundError(default_message)


def _format_precision_config(
    config: dict[str, Any],
    precision: str,
    loss_scale: float,
    loss_scale_window: int,

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Load the parent directory: load_checkpoint('path/global_step42')
2. For Lightning-saved checkpoints, load the top-level checkpoint dir (where the tag subfolders live) per the Fabric docs
3. Verify with the error's suggested parent path printed in the message

Example fix

# before
fabric.load_checkpoint("save/step10/checkpoint", state)

# after
fabric.load_checkpoint("save/step10", state)

from pathlib import Path
p = Path(ckpt_path)
if p.name == "checkpoint" and (p.parent / "checkpoint").is_dir():
    ckpt_path = str(p.parent)  # use the parent tag dir

try:
    fabric.load_checkpoint(path, state)
except FileNotFoundError as e:
    if "parent directory instead" in str(e):
        suggested = str(e).split("parent directory instead: ")[-1].rstrip(".")
        fabric.load_checkpoint(suggested, state)

When it happens

Trigger: load_checkpoint('path/global_step42/checkpoint') or a path ending in the inner checkpoint subfolder of a DeepSpeed save directory; also triggered with remote (fsspec) URIs whose layout matches.

Common situations: Browsing the save dir, seeing the 'checkpoint' folder and copying its path; scripting that globs '**/checkpoint'; loading a Lightning DeepSpeed save for the first time.

Related errors

• {default_message}. It looks like you passed the path to a fi
• The provided path is not a valid DeepSpeed checkpoint: {path
• DeepSpeed was unable to load the checkpoint. Ensure you pass
• You passed in a path to a DeepSpeed config but the path does
• Got FSDPStrategy.load_checkpoint(..., state={state!r}) but a

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