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.

studio: report why launcher recovery failed, not that it was absent (#9924)

Wayne Sletcher3fd29fdcd1c1
diff --git a/tests/python/test_windows_studio_update_launcher.py b/tests/python/test_windows_studio_update_launcher.py
index 2fb0131f9d7..2c4aa77963a 100644
--- a/tests/python/test_windows_studio_update_launcher.py
+++ b/tests/python/test_windows_studio_update_launcher.py
@@ -791,6 +791,95 @@ def test_a_quarantined_away_launcher_with_a_broken_package_still_fails(
_update(studio)
+def test_a_failed_recovery_reports_the_verdict_it_acted_on(monkeypatch, studio, tmp_path, capsys):
+ """#9804: a failed recovery reports why, not that the launcher is absent."""
+ _configure_windows(monkeypatch, studio, tmp_path, launcher = None)
+ monkeypatch.setattr(studio, "_run_setup_script", lambda **_kwargs: None)
+ monkeypatch.setattr(
+ studio.subprocess,
+ "run",
+ lambda argv, **_kwargs: types.SimpleNamespace(returncode = 3),
+ )
+
+ with pytest.raises(studio.typer.Exit):
+ _update(studio)
+
+ err = capsys.readouterr().err
+ assert "the managed Python CLI returned 3 for --version" in err
+ assert "update failed because the updated launcher is not on disk" not in err
+
+
+def test_a_failed_recovery_with_no_interpreter_says_both(monkeypatch, studio, tmp_path, capsys):
+ """No interpreter: the reason itself carries the absence."""
+ scripts, _launcher = _configure_windows(monkeypatch, studio, tmp_path, launcher = None)
+ (scripts / "python.exe").unlink()
+ monkeypatch.setattr(studio, "_run_setup_script", lambda **_kwargs: None)
+ monkeypatch.setattr(studio.subprocess, "run", _successful_version_run())
+
+ with pytest.raises(studio.typer.Exit):
+ _update(studio)
+
+ # Whole clause: __enter__ already prints a "missing or invalid" warning.
+ assert (
+ "the updated launcher is missing and there is no managed interpreter"
+ in capsys.readouterr().err
+ )
+
+
+def test_a_recovered_launcher_still_reports_what_setup_published(
+ monkeypatch, studio, tmp_path, capsys
+):
+ """A broken published launcher is still the reported cause after a successful restore."""
+ scripts, launcher = _configure_windows(monkeypatch, studio, tmp_path)
+ monkeypatch.setattr(
+ studio, "_run_setup_script", lambda **_kwargs: launcher.write_bytes(b"MZ-new")
+ )
+
+ def run(argv, **_kwargs):
+ target = Path(argv[0])
+ if target.name == "unsloth.exe" and target.read_bytes() == ORIGINAL_LAUNCHER:
+ return types.SimpleNamespace(returncode = 0)
+ return types.SimpleNamespace(returncode = 1)
+
+ monkeypatch.setattr(studio.subprocess, "run", run)
+
+ with pytest.raises(studio.typer.Exit):
+ _update(studio)
+
+ err = capsys.readouterr().err
+ assert "the updated launcher returned 1 for --version" in err
+ assert launcher.read_bytes() == ORIGINAL_LAUNCHER
+ assert "The previous launcher was restored." in err
+
+
+def test_a_published_launcher_keeps_its_own_verdict_when_recovery_also_fails(
+ monkeypatch, studio, tmp_path, capsys
+):
+ """The restored copy's failure never replaces the published launcher's."""
+ scripts, launcher = _configure_windows(monkeypatch, studio, tmp_path)
+ published = b"MZ-published"
+ monkeypatch.setattr(
+ studio, "_run_setup_script", lambda **_kwargs: launcher.write_bytes(published)
+ )
+
+ def run(argv, **_kwargs):
+ target = Path(argv[0])
+ if target.name != "unsloth.exe":
+ return types.SimpleNamespace(returncode = 9)
+ if target.read_bytes() == published:
+ return types.SimpleNamespace(returncode = 7)
+ return types.SimpleNamespace(returncode = 8)
+
+ monkeypatch.setattr(studio.subprocess, "run", run)
+
+ with pytest.raises(studio.typer.Exit):
+ _update(studio)
+
+ err = capsys.readouterr().err
+ assert "the updated launcher returned 7 for --version" in err
+ assert "returned 8 for --version" not in err
+
+
def test_a_restorable_launcher_is_restored_before_the_interpreter_is_asked(
monkeypatch, studio, tmp_path
):
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index 7f8561858ec..fb1bb722d57 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -4527,19 +4527,23 @@ class _WindowsLauncherUpdateTransaction:
return False
def _restore_runnable(self) -> bool:
- """Put back the first copy that actually runs. Under Application Control every --version dies in
- CreateProcess, so this degrades to the shape check."""
+ return self._restore_failure_reason() is None
+
+ def _restore_failure_reason(self) -> Optional[str]:
+ """Put back the first copy that actually runs; return why the CLI still cannot, or None.
+ Under Application Control every --version dies in CreateProcess, so this degrades to the
+ shape check."""
if self._launcher_health_error() is None:
- return True
+ return None
candidates = self._recovery_candidates()
for source in candidates:
if self._restore_from(source) and self._launcher_health_error() is None:
- return True
+ return None
# Nothing ran; leave the best candidate rather than whichever was tried last.
if candidates:
self._restore_from(candidates[0])
# Gone, or denied by policy, is still not a broken CLI. Asked only after every candidate.
- return self._recovered_cli_health_error() is None
+ return self._recovered_cli_health_error()
def _launcher_runs_error(self) -> Optional[str]:
"""Whether THIS launcher file starts and answers --version. About the file, not the CLI: the
@@ -4679,10 +4683,16 @@ class _WindowsLauncherUpdateTransaction:
published = self.launcher.exists()
error = self._launcher_health_error()
if error is not None:
- restored = self._restore_runnable()
+ reason = self._restore_failure_reason()
+ restored = reason is None
# Setup publishing nothing is the case this exists for, so restoring is success; a launcher setup DID write that cannot run is a failure.
if published or not restored:
- typer.echo(f"Error: Unsloth Studio update failed because {error}.", err = True)
+ # Absence names no cause (#9804); any other error is the published launcher's own and must win over the restored copy's.
+ cause = reason if error is self._LAUNCHER_ABSENT else None
+ typer.echo(
+ f"Error: Unsloth Studio update failed because {cause or error}.",
+ err = True,
+ )
if restored:
typer.echo("The previous launcher was restored.", err = True)
elif self._retained_backup() is not None: