{"record":{"id":"1cb785e0779bf730","repo":"unslothai/unsloth","slug":"no-trained-checkpoint-at-relative-check-the-r-1cb785","errorCode":null,"errorMessage":"No trained checkpoint at '{relative}'. Check the run/checkpoint name (see GET /p).","messagePattern":"No trained checkpoint at '(.+?)'\\. Check the run/checkpoint name \\(see GET /p\\)\\.","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":404,"severity":"error","filePath":"studio/backend/utils/models/checkpoints.py","lineNumber":295,"sourceCode":"    the two path segments the ``/p`` route matches (so the UI omits a dead link).\n    \"\"\"\n    if not has_preview_model(output_dir):\n        return None\n    try:\n        rel = Path(output_dir).resolve().relative_to(outputs_root().resolve())\n    except (ValueError, OSError):\n        return None\n    parts = rel.parts\n    if not parts or len(parts) > 2:\n        return None\n    return \"/\".join(parts)\n\n\ndef resolve_preview_checkpoint(run: str, checkpoint: Optional[str] = None) -> Path:\n    relative = run if not checkpoint else f\"{run}/{checkpoint}\"\n    path = resolve_output_dir(relative)\n    if not path.is_dir() or not _is_model_dir(path):\n        raise FileNotFoundError(\n            f\"No trained checkpoint at '{relative}'. Check the run/checkpoint name (see GET /p).\"\n        )\n    return path\n\n\ndef list_preview_targets(outputs_dir: str = str(outputs_root())) -> List[dict]:\n    targets: List[dict] = []\n    for run_name, checkpoints, metadata in scan_checkpoints(outputs_dir):\n        for display_name, path, loss in checkpoints:\n            is_latest = display_name == run_name\n            checkpoint = None if is_latest else Path(path).name\n            targets.append(\n                {\n                    \"run\": run_name,\n                    \"checkpoint\": checkpoint,\n                    \"ref\": run_name if is_latest else f\"{run_name}/{checkpoint}\",\n                    \"is_latest\": is_latest,\n                    \"loss\": loss,","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/models/checkpoints.py#L277-L313","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Call GET /p (list_preview_targets) and use an exact run/checkpoint name it returns","Check spelling and separator: the checkpoint is a single path component under the run","Verify the run directory actually contains model files; wait for or re-trigger a checkpoint save if training is ongoing","Confirm the outputs root setting matches where training wrote the run"],"exampleFix":"# before\nresolve_preview_checkpoint('my-run', 'step-2000')\n# FileNotFoundError: No trained checkpoint at 'my-run/step-2000'.\n\n# after\ntargets = list_preview_targets()          # or GET /p\nname = next(t for t in targets if t['run'] == 'my_run')\nresolve_preview_checkpoint('my_run', name['checkpoint'])  # ok","handlingStrategy":"validation","validationCode":"from utils.models.checkpoints import list_preview_targets\n\ndef target_exists(run: str, checkpoint=None) -> bool:\n    wanted = run if checkpoint is None else f\"{run}/{checkpoint}\"\n    for t in list_preview_targets():\n        got = t['run'] if not t.get('checkpoint') else f\"{t['run']}/{t['checkpoint']}\"\n        if got == wanted:\n            return True\n    return False","typeGuard":null,"tryCatchPattern":"try:\n    path = resolve_preview_checkpoint(run, checkpoint)\nexcept FileNotFoundError as e:\n    refresh_target_list_from_get_p()\n    show str(e)  # message names valid options","preventionTips":["Always populate the picker from GET /p, never free-text","Re-list after runs are created/deleted; names are exact-match"],"tags":["checkpoints","training-outputs","file-not-found","preview"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}