{"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":null,"httpStatus":null,"severity":"error","filePath":"extensions/mlx-extension/src/index.ts","lineNumber":405,"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":387,"sourceCodeEnd":423,"githubUrl":"https://github.com/janhq/jan/blob/7205d770c1e097c3daf35a911176410e93bc5564/extensions/mlx-extension/src/index.ts#L387-L423","documentation":"The jan extension's chat() checks whether the local MLX server subprocess is still alive and responsive by hitting its /health endpoint. When the process is alive but the health fetch rejects (connection refused, timeout, reset socket), the model session is unloaded and this error is thrown, telling the user to reload the model.","triggerScenarios":"Calling chat() while the MLX server process is running but its HTTP health endpoint at http://localhost:<port>/health cannot be reached — e.g. the server just died, the port changed, or a firewall/proxy intercepts localhost requests.","commonSituations":"The MLX server crashed mid-session (OOM, bad model weights), the port recorded in sessionInfo is stale after a restart, a system proxy env var routes localhost through a proxy, or IPv6/IPv4 localhost resolution issues.","solutions":["Reload the model (unload then load again) to spawn a fresh MLX server session","Check that no HTTP_PROXY/HTTPS_PROXY env vars intercept localhost and add localhost/127.0.0.1 to NO_PROXY","Verify the session port is not occupied by another process and that the MLX server actually started","Retry the request; transient health-check failures often clear on the next attempt"],"exampleFix":"// before\nawait chat(messages, model)\n// after\ntry {\n  await chat(messages, model)\n} catch (e) {\n  if (e.message.includes('crashed')) {\n    await mlx.reload(model.id)\n    await chat(messages, model)\n  }\n}","handlingStrategy":"try-catch","validationCode":"async function isMlxHealthy(sessionInfo) {\n  try {\n    const res = await fetch(`http://127.0.0.1:${sessionInfo.port}/health`, { signal: AbortSignal.timeout(3000) })\n    return res.ok\n  } catch { return false }\n}\nif (!(await isMlxHealthy(sessionInfo))) await reloadModel(model.id)","typeGuard":"const isAlive = (s) => typeof s === 'object' && s !== null && typeof s.port === 'number' && s.port > 0","tryCatchPattern":"try {\n  await chat(messages, model)\n} catch (e) {\n  if (String(e.message).includes('crashed')) {\n    await reloadModel(model.id)\n    return chat(messages, model)\n  }\n  throw e\n}","preventionTips":["Add NO_PROXY=localhost,127.0.0.1 in environments with HTTP proxies","Poll /health before sending long-running requests","Monitor MLX server memory to avoid OOM crashes","Pin compatible mlx server and extension versions"],"tags":["mlx","health-check","crash","local-server"],"backgroundTag":"connection-refused","analyzedSha":"7205d770c1e097c3daf35a911176410e93bc5564","analyzedAt":"2026-09-17T14:27:30.100Z","contentChangedAt":"2026-09-17T14:27:30.100Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}