{"record":{"id":"4820bd60fe15f7f3","repo":"janhq/jan","slug":"mlx-model-appears-to-have-crashed-please-reload","errorCode":null,"errorMessage":"MLX model appears to have crashed! Please reload!","messagePattern":"MLX model appears to have crashed! Please reload!","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"extensions/mlx-extension/src/index.ts","lineNumber":375,"sourceCode":"    opts: chatCompletionRequest,\n    abortController?: AbortController\n  ): Promise<chatCompletion | AsyncIterable<chatCompletionChunk>> {\n    const sessionInfo = await this.findSessionByModel(opts.model)\n    if (!sessionInfo) {\n      throw new Error(`No active MLX session found for model: ${opts.model}`)\n    }\n\n    // Check if the process is alive\n    const isAlive = await invoke<boolean>('plugin:mlx|is_mlx_process_running', {\n      pid: sessionInfo.pid,\n    })\n\n    if (isAlive) {\n      try {\n        await fetch(`http://localhost:${sessionInfo.port}/health`)\n      } catch (e) {\n        this.unload(sessionInfo.model_id)\n        throw new Error('MLX model appears to have crashed! Please reload!')\n      }\n    } else {\n      throw new Error('MLX model has crashed! Please reload!')\n    }\n\n    const baseUrl = `http://localhost:${sessionInfo.port}/v1`\n    const url = `${baseUrl}/chat/completions`\n    const headers = {\n      'Content-Type': 'application/json',\n      'Authorization': `Bearer ${sessionInfo.api_key}`,\n    }\n\n    const body = JSON.stringify(opts)\n\n    if (opts.stream) {\n      return this.handleStreamingResponse(url, headers, body, abortController)\n    }\n","sourceCodeStart":357,"sourceCodeEnd":393,"githubUrl":"https://github.com/janhq/jan/blob/fad3f12a147d138388a66f0d92a02b2675f65294/extensions/mlx-extension/src/index.ts#L357-L393","documentation":"Thrown by chat() when the MLX process is reported alive (is_mlx_process_running) but the GET /health fetch throws. The process exists yet its HTTP server is not responding — it is wedged, still initializing, or the health endpoint is unreachable. The extension unloads the model first, then throws so the caller reloads.","triggerScenarios":"MLX server process is up but still binding its port or initializing weights when /health is hit; the server hung after a GPU error but did not exit; port mismatch where the recorded port no longer belongs to the server; localhost resolution issue.","commonSituations":"chat() called immediately after load() returned but before the HTTP server was truly ready; transient Metal/GPU fault wedged the server; firewall blocks localhost loopback on the chosen port.","solutions":["Retry chat() after a brief wait; the server may finish booting (the extension already unloaded, so reload first).","Increase the load timeout / readiness wait so /health is live before chat is allowed.","On persistent failure, fully reload the model via load() to spawn a fresh server process.","Check GPU/system resources — a wedged server often follows memory pressure."],"exampleFix":"// before\nconst completion = await engine.chat(opts)\n\n// after\ntry {\n  return await engine.chat(opts)\n} catch (e) {\n  if (/appears to have crashed/.test(String(e))) {\n    await engine.load(opts.model) // reload then retry once\n    return await engine.chat(opts)\n  }\n  throw e\n}","handlingStrategy":"retry","validationCode":"async function mlxHealthReady(port: number): Promise<boolean> {\n  try { return (await fetch(`http://localhost:${port}/health`)).ok }\n  catch { return false }\n}\n\nif (!(await mlxHealthReady(sessionInfo.port))) {\n  throw new Error('MLX /health not ready; wait or reload')\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await engine.chat(opts, abort)\n} catch (e) {\n  if (/appears to have crashed/.test(String(e))) {\n    await engine.load(opts.model) // extension already unloaded it\n    return await engine.chat(opts, abort)\n  }\n  throw e\n}","preventionTips":["Wait for /health 200 after load() before issuing chat.","Increase the load/readiness timeout so the server is ready before chat.","Watch GPU/memory pressure that wedges the server."],"tags":["session","chat","health-check","crash","mlx","typescript"],"backgroundTag":null,"analyzedSha":"fad3f12a147d138388a66f0d92a02b2675f65294","analyzedAt":"2026-08-12T20:33:47.516Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}