unslothai/unsloth · error · ValueError

Resume checkpoint path could not be resolved.

Error message

Resume checkpoint path could not be resolved.

What it means

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.

Source

Thrown at studio/backend/core/training/resume.py:222

    return next(
        (
            str(checkpoint)
            for checkpoint in checkpoints
            if _checkpoint_step(checkpoint) >= 0
            and is_resume_checkpoint_valid(checkpoint, expected_step)
        ),
        None,
    )


def normalize_resume_output_dir(path_value: str) -> str:
    if _is_foreign_absolute_path(path_value):
        raise ValueError("Resume checkpoint uses a path from a different operating system.")
    try:
        path = resolve_output_dir(path_value)
        path.resolve(strict = True)
    except (OSError, RuntimeError) as error:
        raise ValueError("Resume checkpoint path could not be resolved.") from error
    if not _is_under_outputs(path):
        raise ValueError("Resume checkpoint must be inside Unsloth outputs.")
    return str(path)


def training_run_config(run: dict) -> dict:
    raw_config = run.get("config_json")
    if isinstance(raw_config, dict):
        return raw_config
    if not isinstance(raw_config, str) or not raw_config.strip():
        return {}
    try:
        parsed = json.loads(raw_config)
    except (json.JSONDecodeError, TypeError):
        return {}
    return parsed if isinstance(parsed, dict) else {}

View on GitHub (pinned to 203007d190)

Solutions

1. Verify the checkpoint directory actually exists and is readable: ls <path> as the same user running training.
2. If the checkpoint moved, update the resume path (or move the data back) so the original path resolves again.
3. Mount the missing network/external volume, or copy the checkpoint under the local Unsloth outputs directory.
4. If the checkpoint is gone entirely, restart training without resume.

Example fix

// before
normalize_resume_output_dir("outputs/run-42/checkpoint-500")  # dir was deleted
// after
# re-locate an existing checkpoint
normalize_resume_output_dir("outputs/run-42/checkpoint-400")

from pathlib import Path

resume_dir = Path(resume_path)
assert resume_dir.exists() and resume_dir.is_dir(), f"checkpoint dir missing: {resume_dir}"

try:
    normalized = normalize_resume_output_dir(path_value)
except ValueError as e:
    if "could not be resolved" in str(e):
        # path missing/unreachable: verify mount and existence, then retry or restart
        ...

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Execution artifact path is not a dataset folder.
• Local base_repo is not a diffusers pipeline directory (no {i
• Path does not exist
• Path must be a directory, not a file
• Path is not readable

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/791b5ac20447be8c. Report an issue: GitHub.