janhq/jan · error

MLX API request failed with status

Error message

MLX API request failed with status ${response.status}: ${JSON.stringify(errorData)}

What it means

In the non-streaming chat path, if the MLX server's /v1/chat/completions endpoint returns a non-OK HTTP status, the extension reads the error body (best-effort) and throws an error embedding the status code and response payload. This surfaces upstream server-side failures (bad request, model not loaded, server error).

Solutions

1. Read the embedded status and errorData in the message to identify the server-side cause
2. Verify the model is loaded and healthy before calling chat (hit /health)
3. Simplify the request (remove exotic parameters) to isolate which field the server rejects
4. Update the MLX server and extension to matching versions

const health = await fetch(`http://127.0.0.1:${sessionInfo.port}/health`)
if (!health.ok) throw new Error('Model not ready; reload before chat')

const isChatRequestValid = (r) => Array.isArray(r?.messages) && r.messages.length > 0 && typeof r?.model === 'string'

try {
  return await chat(messages, model)
} catch (e) {
  const m = /status (\d+)/.exec(e.message)
  if (m && Number(m[1]) >= 500) throw e // retryable upstream
  console.error('MLX rejected request:', e.message)
  throw e
}

When it happens

Trigger: POST to http://localhost:<port>/v1/chat/completions returns 4xx/5xx — malformed request body, model not loaded in the server, invalid sampling parameters, or internal server error.

Common situations: Sending unsupported parameters (temperature/top_p combos the server rejects), calling chat after the model failed to load properly, MLX server version mismatch with the extension's expected OpenAI-compatible API.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Failed to fetch models from
• API request failed with status
• error.message
• Failed to fetch HuggingFace repository
• Failed to fetch model catalog

AI-assisted analysis of janhq/jan@7205d770c1 (2026-09-17). Data as JSON: /api/errors/7e61adca1554a66d. Report an issue: GitHub.

Appendix: source

Thrown at extensions/mlx-extension/src/index.ts:433

      'Authorization': `Bearer ${sessionInfo.api_key}`,
    }

    const body = JSON.stringify(opts)

    if (opts.stream) {
      return this.handleStreamingResponse(url, headers, body, abortController)
    }

    const response = await fetch(url, {
      method: 'POST',
      headers,
      body,
      signal: abortController?.signal,
    })

    if (!response.ok) {
      const errorData = await response.json().catch(() => null)
      throw new Error(
        `MLX API request failed with status ${response.status}: ${JSON.stringify(errorData)}`
      )
    }

    const completionResponse = (await response.json()) as chatCompletion

    if (completionResponse.choices?.[0]?.finish_reason === 'length') {
      throw new Error(OUT_OF_CONTEXT_SIZE)
    }

    return completionResponse
  }

  private async *handleStreamingResponse(
    url: string,
    headers: HeadersInit,
    body: string,
    abortController?: AbortController

View on GitHub (pinned to 7205d770c1)