Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

CLI: list-checkpoints reports an --outputs-dir outside the outputs folder as an error (#16202)

Henry Su38c5cfa5c10a
diff --git a/studio/backend/utils/models/checkpoints.py b/studio/backend/utils/models/checkpoints.py
index 8f325eac68d..cac61f87147 100644
--- a/studio/backend/utils/models/checkpoints.py
+++ b/studio/backend/utils/models/checkpoints.py
@@ -328,7 +328,7 @@ def _scan_checkpoints(
outputs_path = resolve_output_dir(outputs_dir)
if not outputs_path.exists():
- logger.warning(f"Outputs directory not found: {outputs_dir}")
+ logger.warning(f"Outputs directory not found: {outputs_path}")
return models
try:
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index aa303fbe7ef..b60fef8ccd3 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -3765,7 +3765,7 @@ def scan_trained_models(outputs_dir: Optional[str] = None) -> List[Tuple[str, st
outputs_path = resolve_output_dir(outputs_dir)
if not outputs_path.exists():
- logger.warning(f"Outputs directory not found: {outputs_dir}")
+ logger.warning(f"Outputs directory not found: {outputs_path}")
return trained_models
try:
diff --git a/unsloth_cli/commands/export.py b/unsloth_cli/commands/export.py
index 5a69ced329e..9ec4a46391a 100644
--- a/unsloth_cli/commands/export.py
+++ b/unsloth_cli/commands/export.py
@@ -23,7 +23,12 @@ GGUF_QUANTS = ["q4_k_m", "q5_k_m", "q8_0", "f16"]
def list_checkpoints(
outputs_dir: Path = typer.Option(
- Path("./outputs"), "--outputs-dir", help = "Directory that holds training runs."
+ Path("./outputs"),
+ "--outputs-dir",
+ help = (
+ "Directory that holds training runs, inside Unsloth's outputs folder. "
+ "A relative path is resolved there."
+ ),
),
):
"""List checkpoints detected in the outputs directory."""
@@ -31,7 +36,11 @@ def list_checkpoints(
from studio.backend.core.export import ExportBackend
backend = ExportBackend()
- checkpoints = backend.scan_checkpoints(outputs_dir = str(outputs_dir))
+ try:
+ checkpoints = backend.scan_checkpoints(outputs_dir = str(outputs_dir))
+ except ValueError as exc:
+ typer.echo(f"Error: {exc}", err = True)
+ raise typer.Exit(code = 1)
if not checkpoints:
typer.echo("No checkpoints found.")
raise typer.Exit()
diff --git a/unsloth_cli/tests/test_list_checkpoints_outputs_dir.py b/unsloth_cli/tests/test_list_checkpoints_outputs_dir.py
new file mode 100644
index 00000000000..5557c3f71f8
--- /dev/null
+++ b/unsloth_cli/tests/test_list_checkpoints_outputs_dir.py
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""unsloth list-checkpoints --outputs-dir: a path outside the outputs folder is a usage error, not a traceback."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _list_checkpoints(tmp_path: Path, outputs_dir: Path) -> subprocess.CompletedProcess:
+ env = dict(os.environ)
+ for key in ("STUDIO_HOME", "UNSLOTH_HOME", "UNSLOTH_PORTABLE"):
+ env.pop(key, None)
+ env.update(
+ HOME = str(tmp_path / "home"),
+ UNSLOTH_STUDIO_HOME = str(tmp_path / "studio"),
+ PYTHONPATH = str(REPO_ROOT),
+ NO_COLOR = "1",
+ TERM = "dumb",
+ )
+ return subprocess.run(
+ [
+ sys.executable,
+ "-m",
+ "unsloth_cli",
+ "list-checkpoints",
+ "--outputs-dir",
+ str(outputs_dir),
+ ],
+ cwd = str(tmp_path),
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 300,
+ )
+
+
+def _make_run(outputs: Path) -> Path:
+ checkpoint = outputs / "my_run" / "checkpoint-10"
+ checkpoint.mkdir(parents = True)
+ (checkpoint / "adapter_config.json").write_text("{}")
+ return checkpoint
+
+
+def test_outputs_dir_outside_the_outputs_folder_is_a_usage_error(tmp_path):
+ outside = tmp_path / "project" / "outputs"
+ _make_run(outside)
+
+ result = _list_checkpoints(tmp_path, outside)
+
+ assert result.returncode == 1, result.stdout + result.stderr
+ assert "Traceback" not in result.stdout + result.stderr
+ errors = [line for line in result.stderr.splitlines() if line.startswith("Error: ")]
+ assert errors, result.stderr
+ assert str((tmp_path / "studio" / "outputs").resolve()) in errors[0]
+
+
+def test_missing_outputs_dir_warning_names_the_folder_it_searched(tmp_path):
+ result = _list_checkpoints(tmp_path, Path("runs"))
+
+ assert result.returncode == 0, result.stdout + result.stderr
+ assert "No checkpoints found." in result.stdout
+ assert f"Outputs directory not found: {tmp_path / 'studio' / 'outputs' / 'runs'}" in (
+ result.stdout + result.stderr
+ )
+
+
+def test_outputs_dir_inside_the_outputs_folder_lists_its_checkpoints(tmp_path):
+ checkpoint = _make_run(tmp_path / "studio" / "outputs")
+
+ result = _list_checkpoints(tmp_path, tmp_path / "studio" / "outputs")
+
+ assert result.returncode == 0, result.stdout + result.stderr
+ assert "\nmy_run:\n" in result.stdout
+ assert f"checkpoint-10: {checkpoint.resolve()}" in result.stdout