janhq/jan · error · Error

MLX engine not found

Error message

MLX engine not found

What it means

Thrown when `EngineManager.instance().get('mlx')` returns a falsy value during the MLX download flow. The MLX engine must be registered by the mlx extension before this code runs; absence means the extension is not installed, not enabled, or not registered its engine with the EngineManager singleton.

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

Solutions

1. Confirm the app is running on Apple Silicon macOS (MLX requires Metal).
2. Enable/reinstall the MLX extension from settings and restart the app.
3. Check the extension's engine-registration log during startup for the exact key it uses.
4. Guard the download button so it is disabled when the MLX engine is not present.

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) {
  throw new Error(
    'MLX engine not found. Install/enable the MLX extension (requires Apple Silicon macOS).'
  )
}

const engine = EngineManager.instance().get('mlx')
if (!engine) {
  toast.error('MLX unavailable', {
    description: 'Install/enable the MLX extension (Apple Silicon required).',
  })
  return
}

function isMlxEngine(e: unknown): e is { import(id: string, opts: Record<string, unknown>): Promise<unknown> } {
  return !!e && typeof (e as any).import === 'function'
}

try {
  const engine = EngineManager.instance().get('mlx')
  if (!isMlxEngine(engine)) {
    toast.error('MLX engine not found', { description: 'Apple Silicon + MLX extension required.' })
    return
  }
  // proceed
} catch (error) {
  toast.error('Failed to download MLX model', { description: error instanceof Error ? error.message : String(error) })
}

When it happens

Trigger: User clicks Download on an MLX hub model but the MLX extension is disabled/missing; the extension loaded but failed to register its engine under the key 'mlx'; running on a non-macOS platform where MLX is unsupported and the extension self-disabled.

Common situations: MLX is Apple-Silicon-only — Linux/Windows builds won't register the engine; extension crashed during init; extension build mismatch after an app upgrade; the engine key changed (e.g. 'mlx' vs 'mlx-engine') after a refactor.

Related errors

• MLX engine not found
• Extension does not support CUDA runtime installation
• Platform {platform.system()} not supported
• No supported backend binaries found for this system. Backend
• Unable to find a suitable port for MLX model

AI-assisted analysis of janhq/jan@fad3f12a14 (2026-08-12). Data as JSON: /api/errors/a3458c8c790ea53f. Report an issue: GitHub.