Lightning-AI/pytorch-lightning · error · ValueError

The filename cannot be empty

Error message

The filename cannot be empty

What it means

OnExceptionCheckpoint saves a checkpoint when an exception interrupts training. Its filename becomes part of the checkpoint path immediately at construction (since an exception can occur at any moment), so an empty filename is rejected with ValueError in __init__.

Source

Thrown at src/lightning/pytorch/callbacks/on_exception_checkpoint.py:55

    Raises:
        ValueError:
            If ``filename`` is empty.


    Example:
        >>> from lightning.pytorch import Trainer
        >>> from lightning.pytorch.callbacks import OnExceptionCheckpoint
        >>> trainer = Trainer(callbacks=[OnExceptionCheckpoint(".")])

    """

    FILE_EXTENSION = ".ckpt"

    def __init__(self, dirpath: _PATH, filename: str = "on_exception") -> None:
        super().__init__()
        if not filename:
            raise ValueError("The filename cannot be empty")
        # not optional because an exception could occur at any moment, so we cannot wait until the `setup` hook
        self.dirpath = dirpath
        self.filename = filename

    @property
    def ckpt_path(self) -> str:
        return os.path.join(self.dirpath, self.filename + self.FILE_EXTENSION)

    @override
    def on_exception(self, trainer: "pl.Trainer", *_: Any, **__: Any) -> None:
        # overwrite if necessary
        trainer.save_checkpoint(self.ckpt_path)

    @override
    def teardown(self, trainer: "pl.Trainer", *_: Any, **__: Any) -> None:
        trainer.strategy.remove_checkpoint(self.ckpt_path)

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Provide a non-empty filename string, e.g., filename='on_exception' (the default)
2. Omit the filename argument entirely to use the default 'on_exception'
3. Guard programmatically generated filenames with `filename = filename or 'on_exception'`

Example fix

# before
OnExceptionCheckpoint(dirpath='ckpts', filename='')
# after
OnExceptionCheckpoint(dirpath='ckpts', filename='on_exception')

filename = filename or 'on_exception'
assert filename, 'filename must be non-empty'

def valid_filename(f) -> bool:
    return isinstance(f, str) and len(f.strip()) > 0

When it happens

Trigger: Calling OnExceptionCheckpoint(dirpath=..., filename='') or filename=None (which fails the truthiness check); constructing it programmatically with a computed filename that ends up empty.

Common situations: Passing a filename variable that is empty due to a preceding bug or config omission; passing None expecting a default to kick in (the default is only used when the argument is omitted).

Related errors

• Invalid value for every_n_train_steps={self._every_n_train_s
• Invalid value for every_n_epochs={self._every_n_epochs}. Mus
• `mode` can be {', '.join(mode_dict.keys())} but got {mode}
• `write_interval` should be one of {[i.value for i in WriteIn
• The provided `parameter_names` name: {name} isn't in {self.P

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