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: show the real cause when a desktop install runs out of disk space (#12919)

Hunter Gordond2b4139625d1
diff --git a/studio/frontend/src/app/provider.tsx b/studio/frontend/src/app/provider.tsx
index abd051717d7..1a6ba13fc90 100644
--- a/studio/frontend/src/app/provider.tsx
+++ b/studio/frontend/src/app/provider.tsx
@@ -659,6 +659,7 @@ function TauriWrapper({ children }: { children: ReactNode }) {
status,
logs,
error,
+ installDiskFull,
isExternalServer,
currentStepIndex,
progressDetail,
@@ -958,6 +959,7 @@ function TauriWrapper({ children }: { children: ReactNode }) {
status={startupStatus}
logs={logs}
error={error}
+ diskFull={installDiskFull}
currentStepIndex={currentStepIndex}
progressDetail={startupProgressDetail}
startupMessage={startupMessage}
diff --git a/studio/frontend/src/components/tauri/startup-screen.tsx b/studio/frontend/src/components/tauri/startup-screen.tsx
index b2fded894a6..3e6d44c3485 100644
--- a/studio/frontend/src/components/tauri/startup-screen.tsx
+++ b/studio/frontend/src/components/tauri/startup-screen.tsx
@@ -21,6 +21,7 @@ interface StartupScreenProps {
status: BackendStatus;
logs: string[];
error: string | null;
+ diskFull: boolean;
currentStepIndex: number;
progressDetail: string | null;
startupMessage: StartupMessage;
@@ -188,10 +189,12 @@ function ClosingContent() {
function InstallErrorContent({
error,
+ diskFull,
onRetryInstall,
onCopyDiagnostics,
}: {
error: string | null;
+ diskFull: boolean;
onRetryInstall: () => void;
onCopyDiagnostics: () => Promise<CopySupportDiagnosticsResult>;
}) {
@@ -199,7 +202,9 @@ function InstallErrorContent({
<>
<Logo />
<div className="mt-8 flex flex-col items-center gap-2">
- <p className="text-sm font-medium text-destructive">Setup ran into a problem</p>
+ <p className="text-sm font-medium text-destructive">
+ {diskFull ? "Not enough disk space" : "Setup ran into a problem"}
+ </p>
{error && (
<p className="max-w-xs text-center text-xs text-muted-foreground">{error}</p>
)}
@@ -331,6 +336,7 @@ export function StartupScreen({
status,
logs,
error,
+ diskFull,
currentStepIndex,
progressDetail,
startupMessage,
@@ -360,6 +366,7 @@ export function StartupScreen({
return (
<InstallErrorContent
error={error}
+ diskFull={diskFull}
onRetryInstall={onRetryInstall}
onCopyDiagnostics={onCopyDiagnostics}
/>
diff --git a/studio/frontend/src/hooks/use-tauri-backend.ts b/studio/frontend/src/hooks/use-tauri-backend.ts
index afd4a142017..0ea976897e4 100644
--- a/studio/frontend/src/hooks/use-tauri-backend.ts
+++ b/studio/frontend/src/hooks/use-tauri-backend.ts
@@ -152,6 +152,7 @@ export function useTauriBackend() {
const statusRef = useRef<BackendStatus>(status);
const [logs, setLogs] = useState<string[]>([]);
const [error, setError] = useState<string | null>(null);
+ const [installDiskFull, setInstallDiskFull] = useState(false);
// Guard against double startServer calls
const startingRef = useRef(false);
// Guard against double stopServer calls
@@ -206,18 +207,21 @@ export function useTauriBackend() {
stopManagedEnvironmentWait();
statusRef.current = nextStatus;
setStatus(nextStatus);
+ setInstallDiskFull(false);
syncTrayStatus(nextStatus);
}
function setBackendError(
nextError: string,
nextStatus: BackendStatus = "error",
+ diskFull = false,
) {
if (authFailureRef.current) return;
stopManagedEnvironmentWait();
statusRef.current = nextStatus;
setStatus(nextStatus);
setError(nextError);
+ setInstallDiskFull(diskFull);
syncTrayStatus(nextStatus);
}
@@ -588,6 +592,9 @@ export function useTauriBackend() {
// NEEDS_ELEVATION is not a real error: the Rust side also emits install-needs-elevation (sets
// needs-elevation status). Don't race with it by setting install-error here.
if (msg.includes("NEEDS_ELEVATION")) return;
+ // install-failed is emitted before the command returns and already set this error
+ // with its disk-full flag; setting it again here would clear that flag.
+ if (statusRef.current === "install-error") return;
setBackendError(msg, "install-error");
}
}
@@ -755,8 +762,8 @@ export function useTauriBackend() {
setProgressDetail(e.payload);
});
- register<string>("install-failed", (e) => {
- setBackendError(e.payload, "install-error");
+ register<{ message: string; diskFull: boolean }>("install-failed", (e) => {
+ setBackendError(e.payload.message, "install-error", e.payload.diskFull);
});
register<string>("repair-progress", (e) => {
@@ -869,7 +876,7 @@ export function useTauriBackend() {
}, []);
return {
- status, logs, error, isExternalServer, closing,
+ status, logs, error, installDiskFull, isExternalServer, closing,
currentStepIndex, progressDetail, startupMessage, elevationPackages,
startServer, stopServer, startInstall,
retry, retryInstall, approveElevation, copyDiagnostics,
diff --git a/studio/frontend/tests/install-disk-full-flag.test.ts b/studio/frontend/tests/install-disk-full-flag.test.ts
new file mode 100644
index 00000000000..bd19b7b0514
--- /dev/null
+++ b/studio/frontend/tests/install-disk-full-flag.test.ts
@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// start_install emits install-failed { message, diskFull } and then rejects with the same
+// message. The disk-full dialog has to survive whichever of the two the webview sees last.
+// The hook cannot be rendered, so its functions are lifted by regex, as in
+// managed-environment-wait.test.ts.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrcAsync } from "./helpers/kit.ts";
+
+const src = await readSrcAsync("hooks/use-tauri-backend.ts");
+
+function lift(pattern: RegExp, what: string): string {
+ const found = pattern.exec(src);
+ assert.ok(found, `could not find ${what} in use-tauri-backend.ts`);
+ return found[0];
+}
+
+const statusBody = lift(
+ / function setBackendStatus\([^)]*\) \{[\s\S]*?\n \}\n/,
+ "setBackendStatus",
+);
+const errorBody = lift(
+ / function setBackendError\([\s\S]*?\n \}\n/,
+ "setBackendError",
+);
+const installBody = lift(
+ / async function startInstall\(\) \{[\s\S]*?\n \}\n/,
+ "startInstall",
+);
+const listenerBody = lift(
+ /register<\{ message: string; diskFull: boolean \}>\("install-failed", \(e\) => \{[\s\S]*?\}\);/,
+ "the install-failed listener",
+)
+ .replace(/^[\s\S]*?=> \{/, "")
+ .replace(/\}\);$/, "");
+
+const MESSAGE =
+ "Installation failed: install unsloth failed (exit code 1): No space left on device (os error 28)";
+
+async function failInstall(order: "event-first" | "reject-first") {
+ const state = { status: "", error: null as string | null, diskFull: false };
+ let reject: (reason: string) => void = () => {};
+ const noop = () => {};
+ const scope: Record<string, unknown> = {
+ authFailureRef: { current: null },
+ statusRef: { current: "not-installed" },
+ elevationResumeRef: { current: null },
+ seenStepsRef: { current: new Set() },
+ stopManagedEnvironmentWait: noop,
+ syncTrayStatus: noop,
+ setCurrentStepIndex: noop,
+ setProgressDetail: noop,
+ setLogs: noop,
+ setStatus: (status: string) => {
+ state.status = status;
+ },
+ setError: (error: string | null) => {
+ state.error = error;
+ },
+ setInstallDiskFull: (diskFull: boolean) => {
+ state.diskFull = diskFull;
+ },
+ clearBackendError: () => {
+ state.error = null;
+ },
+ startServer: () => Promise.resolve(),
+ // The bare specifier does not resolve inside `new Function`.
+ importTauriCore: () =>
+ Promise.resolve({
+ invoke: () =>
+ new Promise((_resolve, rejectInvoke) => {
+ reject = rejectInvoke;
+ }),
+ }),
+ };
+ const source = `
+${statusBody.replace(": BackendStatus", "")}
+${errorBody.replace(/: (string|BackendStatus)/g, "")}
+${installBody.replace('await import("@tauri-apps/api/core")', "await importTauriCore()")}
+ return { startInstall, onInstallFailed: (e) => {${listenerBody}} };
+ `;
+ const keys = Object.keys(scope);
+ const hook = new Function(...keys, source)(
+ ...keys.map((key) => scope[key]),
+ ) as {
+ startInstall: () => Promise<void>;
+ onInstallFailed: (e: {
+ payload: { message: string; diskFull: boolean };
+ }) => void;
+ };
+
+ const install = hook.startInstall();
+ await new Promise((resolve) => setImmediate(resolve));
+ const event = { payload: { message: MESSAGE, diskFull: true } };
+ if (order === "event-first") {
+ hook.onInstallFailed(event);
+ reject(MESSAGE);
+ await install;
+ } else {
+ reject(MESSAGE);
+ await install;
+ hook.onInstallFailed(event);
+ }
+ return state;
+}
+
+for (const order of ["event-first", "reject-first"] as const) {
+ test(`a disk-full install keeps its dialog (${order})`, async () => {
+ const state = await failInstall(order);
+ assert.equal(state.status, "install-error");
+ assert.equal(state.error, MESSAGE);
+ assert.equal(state.diskFull, true);
+ });
+}
diff --git a/studio/frontend/tests/managed-environment-wait.test.ts b/studio/frontend/tests/managed-environment-wait.test.ts
index 4ec12c95a24..5569766b69d 100644
--- a/studio/frontend/tests/managed-environment-wait.test.ts
+++ b/studio/frontend/tests/managed-environment-wait.test.ts
@@ -117,6 +117,7 @@ function harness(
setStatus: (status: string) => statuses.push(status),
syncTrayStatus: noop,
setError: (error: string) => errors.push(error),
+ setInstallDiskFull: noop,
setApiBase: noop,
setIsExternalServer: noop,
stopExternalServerPoll: noop,
diff --git a/studio/src-tauri/src/install.rs b/studio/src-tauri/src/install.rs
index a776b3b306f..d1015116105 100644
--- a/studio/src-tauri/src/install.rs
+++ b/studio/src-tauri/src/install.rs
@@ -35,6 +35,37 @@ const FAILURE_CONTEXT_LINE_BYTES: usize = 1_000;
/// Clear labels are a small fixed set; this only bounds a pathological producer.
const MAX_UNPAIRED_CLEARS: usize = 64;
+/// Child-process text that `std` would classify as `ErrorKind::StorageFull`.
+/// uv prints `std::io::Error`'s Display, `{strerror} (os error {code})`:
+/// <https://github.com/rust-lang/rust/blob/master/library/core/src/io/error.rs>
+///
+/// The numeric codes are cfg-gated the same way `std` maps them. On Unix only
+/// ENOSPC (28, "No space left on device") is `StorageFull`; 39 is ENOTEMPTY and
+/// on Linux 112 is EHOSTDOWN. On Windows, 112 and 39 are `ERROR_DISK_FULL` and
+/// `ERROR_HANDLE_DISK_FULL`, and 28 is not a full disk:
+/// <https://github.com/rust-lang/rust/blob/master/library/std/src/sys/io/error/unix.rs>
+/// <https://github.com/rust-lang/rust/blob/master/library/std/src/sys/io/error/windows.rs>
+///
+/// Parentheses keep "(os error 28)" from matching "(os error 280)".
+fn is_disk_full_text(text: &str) -> bool {
+ let lower = text.to_ascii_lowercase();
+ #[cfg(windows)]
+ {
+ lower.contains("not enough space on the disk")
+ || lower.contains("(os error 112)")
+ || lower.contains("(os error 39)")
+ }
+ #[cfg(not(windows))]
+ {
+ lower.contains("no space left on device") || lower.contains("(os error 28)")
+ }
+}
+
+/// install.sh (`_set_disk_full_suffix`) and install.ps1 append this to their
+/// `[TAURI:ERROR_DEFAULT]` message when the studio home has under 64 MiB free.
+/// It is the installers' own English text, so it is the same on every OS.
+const INSTALLER_DISK_FULL_PHRASE: &str = "so the disk is full";
+
fn generic_failure_message(code: i32) -> String {
format!(
"Installation failed with exit code {}. Open the installer logs for details.",
@@ -189,6 +220,17 @@ struct InstallFailureContext {
unpaired_clears: HashMap<(String, InstallOutputStream), usize>,
started: bool,
output_tail: VecDeque<InstallOutputLine>,
+ /// The disk-full line from this stream, kept even after the 8-line tail has
+ /// moved on. uv follows "No space left on device" with a dependency footer
+ /// whose last line is only the package that was unpacking (`sounddevice`),
+ /// and that footer is what the summary would otherwise show. Cleared with
+ /// the stream so a later step does not inherit it.
+ disk_full_line: Option<(InstallOutputStream, String)>,
+ /// True when `explicit_error` was taken from `disk_full_line`. This is the
+ /// flag the UI trusts; it does not re-read OS error numbers.
+ disk_full: bool,
+ /// True when `default_error` is the installer's own low-space diagnosis.
+ default_disk_full: bool,
}
impl InstallFailureContext {
@@ -210,6 +252,7 @@ impl InstallFailureContext {
if !message.is_empty() {
self.explicit_error = Some(Self::bounded_line(message));
self.explicit_error_stream = Some(InstallOutputStream::Stdout);
+ self.disk_full = false;
}
return false;
}
@@ -221,6 +264,7 @@ impl InstallFailureContext {
let message = message.trim();
if !message.is_empty() {
self.default_error = Some(Self::bounded_line(message));
+ self.default_disk_full = message.contains(INSTALLER_DISK_FULL_PHRASE);
}
return true;
}
@@ -250,12 +294,23 @@ impl InstallFailureContext {
fn capture_output_error(&mut self, stream: InstallOutputStream, fallback: &str) {
let fallback = fallback.trim();
+ let from_disk = self
+ .disk_full_line
+ .as_ref()
+ .is_some_and(|(seen, _)| *seen == stream);
let detail = self
- .output_tail
- .iter()
- .rev()
- .find(|line| line.stream == stream)
- .map(|line| line.text.as_str());
+ .disk_full_line
+ .as_ref()
+ .filter(|(seen, _)| *seen == stream)
+ .map(|(_, text)| text.clone())
+ .or_else(|| {
+ self.output_tail
+ .iter()
+ .rev()
+ .find(|line| line.stream == stream)
+ .map(|line| line.text.clone())
+ });
+ let detail = detail.as_deref();
if let Some(error) = match (fallback.is_empty(), detail) {
(_, Some(detail)) if fallback == detail => Some(detail.to_owned()),
(false, Some(detail)) => Some(Self::bounded_line(&format!("{fallback}: {detail}"))),
@@ -265,6 +320,7 @@ impl InstallFailureContext {
} {
self.explicit_error = Some(error);
self.explicit_error_stream = Some(stream);
+ self.disk_full = from_disk;
}
}
@@ -318,15 +374,24 @@ impl InstallFailureContext {
if self.explicit_error_stream == Some(stream) {
self.explicit_error = None;
self.explicit_error_stream = None;
+ self.disk_full = false;
}
if stream == InstallOutputStream::Stdout {
self.default_error = None;
+ self.default_disk_full = false;
}
self.clear_stream(stream);
}
fn clear_stream(&mut self, stream: InstallOutputStream) {
self.output_tail.retain(|line| line.stream != stream);
+ if self
+ .disk_full_line
+ .as_ref()
+ .is_some_and(|(seen, _)| *seen == stream)
+ {
+ self.disk_full_line = None;
+ }
}
fn push_output(&mut self, stream: InstallOutputStream, text: &str) {
@@ -335,6 +400,9 @@ impl InstallFailureContext {
return;
}
let text = Self::bounded_line(text);
+ if is_disk_full_text(&text) {
+ self.disk_full_line = Some((stream, text.clone()));
+ }
self.output_tail
.push_back(InstallOutputLine { stream, text });
while self.output_tail.len() > FAILURE_CONTEXT_LINES {
@@ -350,6 +418,15 @@ impl InstallFailureContext {
text
}
+ /// Whether the failure `message` reports is a full disk: a disk-full output line
+ /// became the error, or the installer's low-space default is what gets shown.
+ fn reports_disk_full(&self) -> bool {
+ self.disk_full
+ || (self.explicit_error.is_none()
+ && self.default_error.is_some()
+ && self.default_disk_full)
+ }
+
fn message(&self, code: i32) -> String {
let detail = self
.explicit_error
@@ -547,9 +624,22 @@ fn emit_mode_progress(app: &AppHandle, mode: InstallEventMode, message: &str) {
let _ = app.emit(mode.progress_event(), message);
}
-fn emit_failed(app: &AppHandle, message: &str) {
+#[derive(Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+struct InstallFailedEvent {
+ message: String,
+ disk_full: bool,
+}
+
+fn emit_failed(app: &AppHandle, message: &str, disk_full: bool) {
error!("[install] FAILED: {}", message);
- let _ = app.emit("install-failed", message);
+ let _ = app.emit(
+ "install-failed",
+ InstallFailedEvent {
+ message: message.to_owned(),
+ disk_full,
+ },
+ );
}
fn emit_complete(app: &AppHandle) {
@@ -930,7 +1020,7 @@ fn run_install_with_event_mode(
diagnostics::finish_attempt(&diagnostics, &attempt, None, false, Some(msg.clone()));
clear_current_attempt(&state);
if event_mode.emit_terminal_events() {
- emit_failed(&app, &msg);
+ emit_failed(&app, &msg, false);
}
return Err(msg);
}
@@ -1008,10 +1098,15 @@ fn run_install_with_event_mode(
let _ = app.emit(event_mode.needs_elevation_event(), &packages);
Err("NEEDS_ELEVATION".to_string())
} else {
- let msg = failure_context
+ let (msg, disk_full) = failure_context
.lock()
- .map(|context| failure_message(&context, code, &script))
- .unwrap_or_else(|_| generic_failure_message(code));
+ .map(|context| {
+ (
+ failure_message(&context, code, &script),
+ context.reports_disk_full(),
+ )
+ })
+ .unwrap_or_else(|_| (generic_failure_message(code), false));
diagnostics::finish_attempt(
&diagnostics,
&attempt,
@@ -1021,7 +1116,7 @@ fn run_install_with_event_mode(
);
clear_current_attempt(&state);
if event_mode.emit_terminal_events() {
- emit_failed(&app, &msg);
+ emit_failed(&app, &msg, disk_full);
}
Err(msg)
}
@@ -1036,7 +1131,7 @@ fn run_install_with_event_mode(
diagnostics::finish_attempt(&diagnostics, &attempt, None, false, Some(msg.clone()));
clear_current_attempt(&state);
if event_mode.emit_terminal_events() {
- emit_failed(&app, &msg);
+ emit_failed(&app, &msg, false);
}
Err(msg)
}
@@ -1930,6 +2025,97 @@ mod tests {
);
}
+ #[test]
+ fn disk_full_is_reported_instead_of_the_package_footer() {
+ let cause = if cfg!(windows) {
+ "There is not enough space on the disk. (os error 112)"
+ } else {
+ "No space left on device (os error 28)"
+ };
+ let mut context = InstallFailureContext::default();
+ context.observe_stderr(" ╰─▶ failed to create file");
+ context.observe_stderr(cause);
+ // Longer than FAILURE_CONTEXT_LINES, which is what hid the cause: uv's
+ // help footer ends on the package name that was being unpacked.
+ for _ in 0..FAILURE_CONTEXT_LINES {
+ context.observe_stderr(" depends on `unsloth-zoo` which depends on `mlx-audio`");
+ }
+ context.observe_stderr(" `sounddevice`");
+ assert!(context.observe_stderr("[TAURI:ERROR_OUTPUT] install unsloth failed (exit code 1)"));
+ assert!(context.disk_full);
+ assert_eq!(
+ context.message(1),
+ format!("Installation failed: install unsloth failed (exit code 1): {cause}")
+ );
+ }
+
+ #[test]
+ fn disk_full_matches_storage_full_for_this_os_only() {
+ assert_eq!(
+ is_disk_full_text("No space left on device (os error 28)"),
+ cfg!(not(windows))
+ );
+ assert_eq!(
+ is_disk_full_text("There is not enough space on the disk. (os error 112)"),
+ cfg!(windows)
+ );
+ assert_eq!(is_disk_full_text("(os error 39)"), cfg!(windows));
+ // Linux 112 is EHOSTDOWN. Windows 28 is not a full disk.
+ assert_eq!(
+ is_disk_full_text("Host is down (os error 112)"),
+ cfg!(windows)
+ );
+ assert!(!is_disk_full_text("enospc"));
+ assert!(!is_disk_full_text("Disk quota exceeded"));
+ assert!(!is_disk_full_text("os error 280"));
+ }
+
+ #[test]
+ fn installer_low_space_default_reports_disk_full() {
+ let mut context = InstallFailureContext::default();
+ context.observe_stdout("Finishing setup");
+ assert!(context.observe_stdout(
+ "[TAURI:ERROR_DEFAULT] studio setup failed (exit code 1): /tmp/studio has only 12 MB free, so the disk is full, which is very likely the cause. Free some space and re-run."
+ ));
+ assert!(context.reports_disk_full());
+ assert!(context.message(1).contains("so the disk is full"));
+ }
+
+ #[test]
+ fn explicit_setup_error_wins_over_the_low_space_default() {
+ let mut context = InstallFailureContext::default();
+ context.observe_stdout("[TAURI:ERROR] llama.cpp setup did not produce a usable server");
+ assert!(context.observe_stdout(
+ "[TAURI:ERROR_DEFAULT] studio setup failed (exit code 1): /tmp/studio has only 12 MB free, so the disk is full, which is very likely the cause. Free some space and re-run."
+ ));
+ assert!(!context.reports_disk_full());
+ assert_eq!(
+ context.message(1),
+ "Installation failed: llama.cpp setup did not produce a usable server"
+ );
+ }
+
+ #[test]
+ fn plain_setup_default_is_not_disk_full() {
+ let mut context = InstallFailureContext::default();
+ assert!(context.observe_stdout("[TAURI:ERROR_DEFAULT] studio setup failed (exit code 4)"));
+ assert!(!context.reports_disk_full());
+ }
+
+ #[test]
+ fn disk_full_does_not_survive_a_cleared_stream() {
+ let mut context = InstallFailureContext::default();
+ context.observe_stderr("No space left on device (os error 28)");
+ assert!(context.observe_stderr("[TAURI:OUTPUT_CLEAR] install unsloth"));
+ context.observe_stderr("resolver error: package not found");
+ assert!(context.observe_stderr("[TAURI:ERROR_OUTPUT] install unsloth failed (exit code 1)"));
+ assert!(!context.disk_full);
+ assert_eq!(
+ context.message(1),
+ "Installation failed: install unsloth failed (exit code 1): resolver error: package not found"
+ );
+ }
+
#[test]
fn command_error_without_output_uses_its_fallback() {
let mut context = InstallFailureContext::default();