Lightning-AI/pytorch-lightning · error · ValueError

You cannot execute `.{fn}(ckpt_path="best")` with `fast_dev_

Error message

You cannot execute `.{fn}(ckpt_path="best")` with `fast_dev_run=True`. Please pass an exact checkpoint path to `.{fn}(ckpt_path=...)`

What it means

Raised when ckpt_path="best" is used but no best_model_path exists yet and fast_dev_run=True. Fast-dev-run runs a single batch/epoch and skips checkpoint saving, so there is never a best checkpoint to resolve; Lightning asks for an explicit path instead.

Source

Thrown at src/lightning/pytorch/trainer/connectors/checkpoint_connector.py:171

                + f" You can pass `.{fn}(ckpt_path='best')` to use the best model or"
                f" `.{fn}(ckpt_path='last')` to use the last model."
                " If you pass a value, this warning will be silenced."
            )

        if ckpt_path == "best":
            if len(self.trainer.checkpoint_callbacks) > 1:
                rank_zero_warn(
                    f'`.{fn}(ckpt_path="best")` is called with Trainer configured with multiple `ModelCheckpoint`'
                    " callbacks. It will use the best checkpoint path from first checkpoint callback."
                )

            if not self.trainer.checkpoint_callback:
                raise ValueError(f'`.{fn}(ckpt_path="best")` is set but `ModelCheckpoint` is not configured.')

            has_best_model_path = self.trainer.checkpoint_callback.best_model_path
            if hasattr(self.trainer.checkpoint_callback, "best_model_path") and not has_best_model_path:
                if self.trainer.fast_dev_run:
                    raise ValueError(
                        f'You cannot execute `.{fn}(ckpt_path="best")` with `fast_dev_run=True`.'
                        f" Please pass an exact checkpoint path to `.{fn}(ckpt_path=...)`"
                    )
                raise ValueError(
                    f'`.{fn}(ckpt_path="best")` is set but `ModelCheckpoint` is not configured to save the best model.'
                )
            # load best weights
            ckpt_path = getattr(self.trainer.checkpoint_callback, "best_model_path", None)

        elif ckpt_path == "last":
            candidates = {getattr(ft, "ckpt_path", None) for ft in ft_checkpoints}
            for callback in self.trainer.checkpoint_callbacks:
                if isinstance(callback, ModelCheckpoint):
                    candidates |= callback._find_last_checkpoints(self.trainer)
            candidates_fs = {path: get_filesystem(path) for path in candidates if path}
            candidates_ts = {path: fs.modified(path) for path, fs in candidates_fs.items() if fs.exists(path)}
            if not candidates_ts:
                # not an error so it can be set and forget before the first `fit` run

View on GitHub (pinned to 9fed5c27d2)

Solutions

Pass an exact checkpoint path: trainer.test(ckpt_path="path/to/file.ckpt")
Use ckpt_path=None to test with the current in-memory weights
Disable fast_dev_run for the fit run so a best checkpoint gets saved before requesting "best"

Example fix

# before
trainer = Trainer(fast_dev_run=True)
trainer.fit(model)
trainer.test(ckpt_path="best")
# after
trainer = Trainer(fast_dev_run=True)
trainer.fit(model)
trainer.test(ckpt_path="runs/epoch=2-step=123.ckpt")  # or ckpt_path=None

Defensive patterns

Strategy: validation

Validate before calling

if trainer.fast_dev_run:
    assert ckpt_path not in ("best", "last") or trainer.checkpoint_callback.best_model_path, \
        "fast_dev_run saves no checkpoints; pass an explicit path"

Prevention

Branch eval logic: fast_dev_run -> ckpt_path=None or explicit path
Treat fast_dev_run as a pipeline smoke test, not a checkpoint producer

When it happens

Trigger: trainer.test(ckpt_path="best") / .validate() / .predict() on a Trainer configured with fast_dev_run=True where the checkpoint callback has no best_model_path (nothing was saved).

Common situations: Smoke-testing pipelines with fast_dev_run=True while reusing eval code that requests the best checkpoint; CI quick checks.

Related errors

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