Lightning-AI/pytorch-lightning · error · ValueError

The path {str(path)!r} does not point to a valid checkpoint.

Error message

The path {str(path)!r} does not point to a valid checkpoint. Make sure the path points to either a directory with FSDP checkpoint shards, or a single file with a full checkpoint.

What it means

The FSDP strategy's load_checkpoint could not interpret the given path as an FSDP checkpoint. It expects either a directory containing FSDP checkpoint shards (a distributed checkpoint produced with _save_distributed_checkpoint=True) or a single file holding a full checkpoint. If the path is neither, Lightning raises this ValueError.

Source

Thrown at src/lightning/pytorch/strategies/fsdp.py:693

                )

            # rank0_only should be false because we need to load the optimizer state on all ranks
            with _get_full_state_dict_context(self.model, world_size=self.world_size, rank0_only=False):
                for optimizer, opt_state in zip(self.optimizers, optimizer_states):
                    if isinstance(list(opt_state["state"].keys())[0], int):
                        # Handling the case where the optimizer state is saved from a normal optimizer
                        opt_state = FSDP.rekey_optim_state_dict(opt_state, OptimStateKeyType.PARAM_NAME, self.model)

                    opt_state = FSDP.optim_state_dict_to_load(
                        optim_state_dict=opt_state,
                        model=self.model,
                        optim=optimizer,
                    )
                    optimizer.load_state_dict(opt_state)

            return checkpoint

        raise ValueError(
            f"The path {str(path)!r} does not point to a valid checkpoint. Make sure the path points to either a"
            " directory with FSDP checkpoint shards, or a single file with a full checkpoint."
        )

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Verify the path exists and inspect its contents: a sharded dir must contain *.distcp files plus a .metadata file; a full checkpoint must be a loadable torch .pt/.ckpt file
2. If the checkpoint is a directory of shards, ensure the FSDPStrategy was created with _save_distributed_checkpoint=True (or use torch.distributed.checkpoint loading)
3. Re-save the checkpoint from the source run in the format matching your loading strategy (sharded dir vs single file)
4. Check the path spelling / use trainer's ModelCheckpoint last/best path helpers instead of hand-built strings

Example fix

# before
trainer.fit(model, ckpt_path="checkpoints/fsdp_run/")  # dir has no .metadata

# after
# ensure the dir is a real DCP sharded checkpoint, or point at the full file
trainer.fit(model, ckpt_path="checkpoints/fsdp_run/last.ckpt")

from pathlib import Path
p = Path(path)
is_sharded = p.is_dir() and (p / ".metadata").exists() and any(p.glob("*.distcp"))
is_full = p.is_file() and p.suffix in {".ckpt", ".pt", ".pth"}
assert is_sharded or is_full, f"{path} is neither a sharded FSDP dir nor a full checkpoint file"

try:
    strategy.load_checkpoint(path)
except ValueError as e:
    if "does not point to a valid checkpoint" in str(e):
        # fall back: try alternate dir/file resolution or TorchCheckpointIO
        ...

When it happens

Trigger: Calling trainer.checkpoint_callback / strategy.load_checkpoint('path') where path is a nonexistent file, a non-checkpoint file, or an empty/non-sharded directory; loading a directory of FSDP shards without the matching metadata (__0_0.distcp + .metadata) or loading a full-checkpoint file when the strategy is configured for distributed checkpoints (mismatch).

Common situations: Passing a .ckpt saved by a non-FSDP run or a DDP checkpoint; passing a path to a directory that only looks like a sharded checkpoint (e.g. missing .metadata); typo in ckpt_path; resuming with a path saved under a different Lightning version.

Related errors

• Found multiple FSDP models in the given state. Saving checkp
• Got FSDPStrategy.load_checkpoint(..., state={state!r}) but a
• Loading a single optimizer object from a checkpoint is not s
• Could not find a FSDP model in the provided checkpoint state
• Found multiple FSDP models in the given state. Loading check

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