unslothai/unsloth · error · ValueError

Resume checkpoint uses a path from a different operating sys

Error message

Resume checkpoint uses a path from a different operating system.

What it means

Raised by normalize_resume_output_dir when the supplied resume path is absolute under a foreign OS path flavor — e.g. 'C:\models\out' on Linux or '/data/out' on Windows. The helper _is_foreign_absolute_path (resume.py:15) detects this via PureWindowsPath/PurePosixPath, because Path() on the host OS cannot treat it as absolute and later resolution would silently produce a wrong relative path. The guard runs before resolve_output_dir so training never resumes from a bogus location.

Source

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

        return None
    if is_resume_checkpoint_valid(path, expected_step):
        return str(path)

    checkpoints = sorted(path.glob("checkpoint-*"), key = _checkpoint_step, reverse = True)
    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)

View on GitHub (pinned to 203007d190)

Solutions

1. Point resume at a checkpoint path that is absolute for the current OS, or use a relative path under the Unsloth outputs root.
2. If the checkpoint lives on another machine, copy it under the local outputs directory first and resume from the local copy.
3. Re-run training from scratch if the foreign checkpoint is not available locally.

Example fix

// before
normalize_resume_output_dir("C:\\unsloth\\outputs\\checkpoint-100")  # on Linux
// after
normalize_resume_output_dir("outputs/my-run/checkpoint-100")  # relative, resolves under local outputs root

from pathlib import PureWindowsPath, PurePosixPath, Path

def is_native_or_relative(path_value: str) -> bool:
    native = Path(path_value)
    return native.is_absolute() or not (
        PureWindowsPath(path_value).is_absolute() or PurePosixPath(path_value).is_absolute()
    )

assert is_native_or_relative(resume_path), "resume path is for another OS"

def is_safe_resume_path(path_value: str) -> bool:
    return isinstance(path_value, str) and is_native_or_relative(path_value)

try:
    normalized = normalize_resume_output_dir(path_value)
except ValueError as e:
    if "different operating system" in str(e):
        # re-point resume at a native path under outputs
        ...

When it happens

Trigger: Calling normalize_resume_output_dir('C:\\Users\\me\\outputs\\run1') on a Linux server, or normalize_resume_output_dir('/home/me/outputs/run1') on Windows; typically when a run config or UI state was copied between machines with different operating systems.

Common situations: Training started on Windows and the checkpoint path was saved into a config/DB, then the same config is reused on a Linux training box (or vice versa); hand-edited YAML/JSON resume fields with backslashes; CI runners on a different OS than the developer workstation.

Related errors

• Resume checkpoint must be inside Unsloth outputs.
• Resume checkpoint path could not be resolved.
• Path under {prefix} is not allowed
• The Hugging Face cache folder is invalid.
• Choose a folder inside the filesystem or drive root.

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