feat: add portable backend manager script and document Windows exit code 3221225781 troubleshooting

README.md

@@ -136,6 +136,7 @@ Typical generation times for an image with **20 steps** (e.g. 512x512 resolution
 *   **Port Conflicts:** The frontend uses `1420` by default. The backend tries `8080` first, then automatically falls back to a free port if `8080` is already busy.
 *   **Linux backends fail to start with `GLIBC_2.38' not found`:** The prebuilt binaries require glibc 2.38+ (Ubuntu 24.04). Upgrade your distribution or build stable-diffusion.cpp from source (see below).
 *   **Linux ROCm not loading:** Make sure your AMD GPU and kernel are compatible with ROCm 7.13. The app will automatically fall back to Vulkan if ROCm cannot initialize.
+*   **Windows exits with code `3221225781`:** This is `0xC0000135`, which means Windows could not load a required backend DLL. For AMD/Intel Vulkan, update the GPU driver with Vulkan support, then rerun setup so `app/backend/win/vulkan/` is repaired. For NVIDIA CUDA, update the NVIDIA driver and rerun setup so CUDA runtime DLLs are restored.
 *   **Generation shows "server is not responding or crashed":** The backend process exited. Check the terminal where you ran `./start.sh` for the exact error (common causes are glibc mismatch, missing Vulkan drivers, or out-of-memory).
 
 ---

scripts/serve.cjs

@@ -661,9 +661,10 @@ function getBackendOptions() {
 function backendAccepts(binaryPath, backendName) {
   if (!binaryPath || !fs.existsSync(binaryPath)) return false;
   try {
+    const cliBackendName = backendName === "metal" ? "metal0" : backendName;
     const probeArgs = [
-      "--backend", backendName,
-      "--params-backend", backendName,
+      "--backend", cliBackendName,
+      "--params-backend", cliBackendName,
       "--model", path.join(MODELS, "__backend_probe_missing__.safetensors"),
       "--listen-port", "18082",
     ];
@@ -692,7 +693,7 @@ function backendAccepts(binaryPath, backendName) {
     }
 
     const lower = output.toLowerCase();
-    if (lower.includes("backend config failed") || output.includes(`backend '${backendName}' was not found`)) {
+    if (lower.includes("backend config failed") || output.includes(`backend '${backendName}' was not found`) || output.includes(`backend '${cliBackendName}' was not found`)) {
       return false;
     }
     // Reject binaries that fail at the dynamic linker / glibc level.
@@ -926,8 +927,8 @@ async function startBackend(settings = {}) {
     );
   } else if (requestedBackend === "metal") {
     args.push(
-      "--backend", "metal",
-      "--params-backend", "metal",
+      "--backend", "metal0",
+      "--params-backend", "metal0",
       "--rng", "cpu",
       "--sampler-rng", "cpu",
     );
@@ -1092,7 +1093,7 @@ async function startBackend(settings = {}) {
     console.log("  [backend] exited with code", code);
     if (code !== null && code !== 0) {
       if (!backendError) {
-        backendError = `exited with code ${code}`;
+        backendError = describeBackendExitCode(code, currentSettings.backendBinary || BACKEND_PATH);
       }
     }
     backendLoadState.active = false;
@@ -1447,6 +1448,30 @@ function describeBackendError(rawError, modelPath) {
   return `${raw}\n\nThe backend could not create the model context. Common causes are a corrupt/incomplete model file, unsupported checkpoint type, or not enough free RAM/VRAM. Delete and re-download the model, then try CPU or Vulkan mode at 512x512.`;
 }
 
+function describeBackendExitCode(code, backendPath) {
+  const numericCode = Number(code);
+  if (osPlatform === "win32" && numericCode === 3221225781) {
+    const backendName = path.basename(backendPath || BACKEND_PATH || "backend");
+    const lowerBackend = backendName.toLowerCase();
+    const isVulkan = lowerBackend.includes("vulkan");
+    const isCuda = lowerBackend.includes("cuda");
+    const likelyMissing = isVulkan
+      ? "the Vulkan runtime/driver DLL, such as vulkan-1.dll"
+      : isCuda
+        ? "a CUDA runtime DLL or NVIDIA driver component"
+        : "a required backend DLL";
+    const driverHint = isVulkan
+      ? "Install or update the GPU vendor driver with Vulkan support, then run setup again so the Vulkan backend folder is repaired."
+      : isCuda
+        ? "Install or update the NVIDIA driver, then run setup again so the CUDA backend folder is repaired."
+        : "Update the GPU driver, then run setup again so the backend folder is repaired.";
+
+    return `exited with code ${code} (0xC0000135: required DLL not found).\n\nWindows could not start ${backendName} because ${likelyMissing} is missing or not loadable. ${driverHint}\n\nIf you are using an AMD/Intel GPU, update the AMD/Intel graphics driver first. If the GPU is too old for the current Vulkan backend, switch the backend to CPU.`;
+  }
+
+  return `exited with code ${code}`;
+}
+
 function getModelInfo(filename) {
   const safeFilename = path.basename(filename || "");
   const stats = fs.statSync(path.join(MODELS, safeFilename));