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

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));