{"record":{"id":"791b5ac20447be8c","repo":"unslothai/unsloth","slug":"resume-checkpoint-path-could-not-be-resolved","errorCode":null,"errorMessage":"Resume checkpoint path could not be resolved.","messagePattern":"Resume checkpoint path could not be resolved\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/training/resume.py","lineNumber":222,"sourceCode":"    return next(\n        (\n            str(checkpoint)\n            for checkpoint in checkpoints\n            if _checkpoint_step(checkpoint) >= 0\n            and is_resume_checkpoint_valid(checkpoint, expected_step)\n        ),\n        None,\n    )\n\n\ndef normalize_resume_output_dir(path_value: str) -> str:\n    if _is_foreign_absolute_path(path_value):\n        raise ValueError(\"Resume checkpoint uses a path from a different operating system.\")\n    try:\n        path = resolve_output_dir(path_value)\n        path.resolve(strict = True)\n    except (OSError, RuntimeError) as error:\n        raise ValueError(\"Resume checkpoint path could not be resolved.\") from error\n    if not _is_under_outputs(path):\n        raise ValueError(\"Resume checkpoint must be inside Unsloth outputs.\")\n    return str(path)\n\n\ndef training_run_config(run: dict) -> dict:\n    raw_config = run.get(\"config_json\")\n    if isinstance(raw_config, dict):\n        return raw_config\n    if not isinstance(raw_config, str) or not raw_config.strip():\n        return {}\n    try:\n        parsed = json.loads(raw_config)\n    except (json.JSONDecodeError, TypeError):\n        return {}\n    return parsed if isinstance(parsed, dict) else {}\n\n","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/training/resume.py#L204-L240","documentation":"Raised when resolve_output_dir(path_value) or the subsequent path.resolve(strict=True) raises OSError or RuntimeError while normalizing a resume checkpoint directory. This means the path exists syntactically but cannot be resolved on disk — the directory (or a component of it) does not exist, is a broken symlink, or is unreachable (unmounted network drive, permission-denied parent). It wraps the underlying OS error with ValueError for a clean API boundary.","triggerScenarios":"Calling normalize_resume_output_dir with a path that does not exist on disk (deleted checkpoint), a dangling symlink, a parent directory on an unmounted NFS/SMB share, or a directory the process lacks permission to traverse; resolve(strict=True) then raises FileNotFoundError/PermissionError (both OSError).","commonSituations":"Checkpoint directories cleaned up by a retention policy or manual cleanup before resume; checkpoint on an external drive that is not mounted; stale DB/UI state referencing a run that was moved; permission changes after copying outputs between users.","solutions":["Verify the checkpoint directory actually exists and is readable: ls <path> as the same user running training.","If the checkpoint moved, update the resume path (or move the data back) so the original path resolves again.","Mount the missing network/external volume, or copy the checkpoint under the local Unsloth outputs directory.","If the checkpoint is gone entirely, restart training without resume."],"exampleFix":"// before\nnormalize_resume_output_dir(\"outputs/run-42/checkpoint-500\")  # dir was deleted\n// after\n# re-locate an existing checkpoint\nnormalize_resume_output_dir(\"outputs/run-42/checkpoint-400\")","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\nresume_dir = Path(resume_path)\nassert resume_dir.exists() and resume_dir.is_dir(), f\"checkpoint dir missing: {resume_dir}\"","typeGuard":null,"tryCatchPattern":"try:\n    normalized = normalize_resume_output_dir(path_value)\nexcept ValueError as e:\n    if \"could not be resolved\" in str(e):\n        # path missing/unreachable: verify mount and existence, then retry or restart\n        ...","preventionTips":["Verify the checkpoint directory exists and is readable right before requesting resume.","Keep checkpoints on local storage; avoid resuming from removable/network volumes that may be unmounted.","Log the resolved absolute path when a run finishes so resume state is unambiguous."],"tags":["filesystem","training-resume","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}