{"record":{"id":"c1d167695ebee4a0","repo":"Lightning-AI/pytorch-lightning","slug":"modelcheckpoint-save-last-link-is-only-suppor","errorCode":null,"errorMessage":"`ModelCheckpoint(save_last='link')` is only supported for local file paths, got `dirpath={dirpath}`.","messagePattern":"`ModelCheckpoint\\(save_last='link'\\)` is only supported for local file paths, got `dirpath=(.+?)`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/callbacks/model_checkpoint.py","lineNumber":331,"sourceCode":"    def state_key(self) -> str:\n        return self._generate_state_key(\n            monitor=self.monitor,\n            mode=self.mode,\n            every_n_train_steps=self._every_n_train_steps,\n            every_n_epochs=self._every_n_epochs,\n            train_time_interval=self._train_time_interval,\n        )\n\n    @override\n    def setup(self, trainer: \"pl.Trainer\", pl_module: \"pl.LightningModule\", stage: str) -> None:\n        dirpath = self.__resolve_ckpt_dir(trainer)\n        dirpath = trainer.strategy.broadcast(dirpath)\n        self.dirpath = dirpath\n        self._fs = get_filesystem(self.dirpath or \"\")\n        if trainer.is_global_zero and stage == \"fit\":\n            self.__warn_if_dir_not_empty(self.dirpath)\n        if self.save_last == \"link\" and not _is_local_file_protocol(self.dirpath):\n            raise ValueError(\n                f\"`ModelCheckpoint(save_last='link')` is only supported for local file paths, got `dirpath={dirpath}`.\"\n            )\n\n    @override\n    def on_train_start(self, trainer: \"pl.Trainer\", pl_module: \"pl.LightningModule\") -> None:\n        self._last_time_checked = time.monotonic()\n\n    @override\n    def on_train_batch_end(\n        self,\n        trainer: \"pl.Trainer\",\n        pl_module: \"pl.LightningModule\",\n        outputs: STEP_OUTPUT,\n        batch: Any,\n        batch_idx: int,\n    ) -> None:\n        \"\"\"Save checkpoint on train batch end if we meet the criteria for `every_n_train_steps`\"\"\"\n        # For manual optimization, we need to handle saving differently","sourceCodeStart":313,"sourceCodeEnd":349,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/callbacks/model_checkpoint.py#L313-L349","documentation":"ModelCheckpoint's `save_last='link'` creates a filesystem symlink ('last.ckpt' -> best checkpoint), which only works on local paths. In `setup()`, if `save_last == 'link'` and the dirpath scheme isn't a local file protocol (e.g. s3://, gs://), a ValueError is raised.","triggerScenarios":"`ModelCheckpoint(dirpath='s3://bucket/ckpt', save_last='link')` or letting default dirpath resolve to a remote fsspec URL, then starting a fit. Only the 'link' mode is restricted; `save_last=True` (copy) works remotely.","commonSituations":"Cloud storage checkpoints on S3/GCS/Azure; Lightning's default remote checkpointing in cluster setups; switching a working local config to a remote dirpath without changing save_last.","solutions":["Use `save_last=True` instead of 'link' for remote paths (copies rather than symlinks)","Or keep dirpath local (e.g. './checkpoints') and sync to remote separately","Or use 'link' only where the filesystem supports symlinks"],"exampleFix":"# before\nModelCheckpoint(dirpath='s3://my-bucket/run1', save_last='link')\n# after\nModelCheckpoint(dirpath='s3://my-bucket/run1', save_last=True)","handlingStrategy":"validation","validationCode":"from urllib.parse import urlparse\nscheme = urlparse(dirpath or '').scheme\nif save_last == 'link' and scheme not in ('', 'file'):\n    save_last = True  # fall back to copy for remote storage","typeGuard":"def link_save_last_ok(dirpath: str) -> bool:\n    from urllib.parse import urlparse\n    return urlparse(dirpath or '').scheme in ('', 'file')","tryCatchPattern":null,"preventionTips":["Default to save_last=True; only use 'link' when dirpath is local","Sync local checkpoints to remote storage as a separate step"],"tags":["lightning","model-checkpoint","remote-storage","symlink"],"backgroundTag":"unsupported-filesystem-operation","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}