unslothai/unsloth · error · FileNotFoundError

No trained checkpoint at '{relative}'. Check the run/checkpo

Error message

No trained checkpoint at '{relative}'. Check the run/checkpoint name (see GET /p).

What it means

resolve_preview_checkpoint() builds 'run' or 'run/checkpoint', resolves it under the outputs directory, and raises FileNotFoundError when the path is not a directory or _is_model_dir() rejects it (no recognizable model artifacts). The message points at GET /p, the endpoint backed by list_preview_targets(), because most failures are name mismatches rather than missing files.

Source

Thrown at studio/backend/utils/models/checkpoints.py:295

    the two path segments the ``/p`` route matches (so the UI omits a dead link).
    """
    if not has_preview_model(output_dir):
        return None
    try:
        rel = Path(output_dir).resolve().relative_to(outputs_root().resolve())
    except (ValueError, OSError):
        return None
    parts = rel.parts
    if not parts or len(parts) > 2:
        return None
    return "/".join(parts)


def resolve_preview_checkpoint(run: str, checkpoint: Optional[str] = None) -> Path:
    relative = run if not checkpoint else f"{run}/{checkpoint}"
    path = resolve_output_dir(relative)
    if not path.is_dir() or not _is_model_dir(path):
        raise FileNotFoundError(
            f"No trained checkpoint at '{relative}'. Check the run/checkpoint name (see GET /p)."
        )
    return path


def list_preview_targets(outputs_dir: str = str(outputs_root())) -> List[dict]:
    targets: List[dict] = []
    for run_name, checkpoints, metadata in scan_checkpoints(outputs_dir):
        for display_name, path, loss in checkpoints:
            is_latest = display_name == run_name
            checkpoint = None if is_latest else Path(path).name
            targets.append(
                {
                    "run": run_name,
                    "checkpoint": checkpoint,
                    "ref": run_name if is_latest else f"{run_name}/{checkpoint}",
                    "is_latest": is_latest,
                    "loss": loss,

View on GitHub (pinned to 203007d190)

Solutions

1. Call GET /p (list_preview_targets) and use an exact run/checkpoint name it returns
2. Check spelling and separator: the checkpoint is a single path component under the run
3. Verify the run directory actually contains model files; wait for or re-trigger a checkpoint save if training is ongoing
4. Confirm the outputs root setting matches where training wrote the run

Example fix

# before
resolve_preview_checkpoint('my-run', 'step-2000')
# FileNotFoundError: No trained checkpoint at 'my-run/step-2000'.

# after
targets = list_preview_targets()          # or GET /p
name = next(t for t in targets if t['run'] == 'my_run')
resolve_preview_checkpoint('my_run', name['checkpoint'])  # ok

from utils.models.checkpoints import list_preview_targets

def target_exists(run: str, checkpoint=None) -> bool:
    wanted = run if checkpoint is None else f"{run}/{checkpoint}"
    for t in list_preview_targets():
        got = t['run'] if not t.get('checkpoint') else f"{t['run']}/{t['checkpoint']}"
        if got == wanted:
            return True
    return False

try:
    path = resolve_preview_checkpoint(run, checkpoint)
except FileNotFoundError as e:
    refresh_target_list_from_get_p()
    show str(e)  # message names valid options

When it happens

Trigger: resolve_preview_checkpoint('my-run') when the run folder is named 'my_run', a checkpoint name that does not exist ('step-2000' vs 'checkpoint-2000'), a run directory that exists but contains no model files (training still in progress or crashed before a save), or an outputs root pointed elsewhere. The relative form is capped at two components (len(parts) <= 2).

Common situations: Previewing immediately after renaming/moving a run; typos in the run name; guessing an epoch checkpoint naming scheme; a run whose save was interrupted so _is_model_dir sees no weights; stale UI list after runs were deleted.

Related errors

• Local model path does not exist: {repo_id}
• no .safetensors/.gguf LoRA file found in '{repo_id}'
• {exc}
• Local model path '{repo_id}' does not exist.
• data_dir is not a directory: {data_dir}

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