janhq/jan · error

MLX engine not found

Error message

MLX engine not found

What it means

Thrown when EngineManager.instance().get('mlx') returns no engine, meaning the MLX extension is not installed, not registered, or not yet initialized. The MLX download/import flow requires the engine to hand off file downloads, so it fails fast.

Solutions

1. Install or re-enable the MLX extension (jan-mlx-extension) in Settings > Extensions
2. Restart the app so engines re-register with the EngineManager
3. Wait for extension initialization to finish before retrying the import
4. Confirm your platform supports MLX (Apple Silicon / macOS) or use the llama.cpp provider instead

Example fix

// before
const engine = EngineManager.instance().get('mlx')
if (!engine) throw new Error('MLX engine not found')
// after
const engine = EngineManager.instance().get('mlx')
if (!engine) {
  window.toast?.error('The MLX extension is not active. Enable it in Settings > Extensions and retry.')
  return
}

const mlxEngine = EngineManager.instance().get('mlx')
if (!mlxEngine) {
  showToast('The MLX extension is not active. Enable it in Settings > Extensions.')
  return
}

const isMlxEngineAvailable = (): boolean =>
  !!EngineManager.instance().get('mlx')

try {
  await runMlxDownload(modelPath)
} catch (e) {
  if (e.message === 'MLX engine not found') {
    openExtensionsSettings('mlx')
  }
}

When it happens

Trigger: Calling the MLX model download action while the 'mlx' engine is absent from the EngineManager — e.g. the MLX extension is disabled, failed to load, is still initializing, or the app build does not bundle it.

Common situations: User uninstalled or disabled the MLX extension; the extension crashed during startup; attempting MLX import on a platform where MLX is not supported; calling the action before engine registration completes.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• MLX engine not found
• Vector DB extension not available
• Conversational extension not available yet
• Extension does not support backend installation
• Extension does not support backend updates

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

Appendix: source

Thrown at web-app/src/containers/MlxModelDownloadAction.tsx:136

        .fetchHuggingFaceRepo(modelPath, huggingfaceToken)

      if (!repoInfo || !repoInfo.siblings) {
        throw new Error('Failed to fetch repository files')
      }

      // Filter relevant model files for MLX
      const modelFiles = repoInfo.siblings

      if (modelFiles.length === 0) {
        throw new Error('No MLX model files found in repository')
      }

      // Get the MLX engine and import
      const engine = EngineManager.instance().get(
        'mlx'
      )
      if (!engine) {
        throw new Error('MLX engine not found')
      }

      // For MLX, we download the first safetensors file as the main model
      // and the extension will download all related files
      const mainSafetensorsFile = modelFiles.find((f) =>
        f.rfilename.toLowerCase().endsWith('.safetensors')
      )

      if (!mainSafetensorsFile) {
        throw new Error('No safetensors file found in repository')
      }

      const modelUrl = `https://huggingface.co/${modelPath}/resolve/main/${mainSafetensorsFile.rfilename}`

      // Prepare additional files to download (all model files except main safetensors)
      // Don't pass sha256/size to skip verification for MLX models
      const extraFiles = modelFiles
        .filter((f) => f.rfilename !== mainSafetensorsFile.rfilename)

View on GitHub (pinned to 7205d770c1)