{"record":{"id":"a3458c8c790ea53f","repo":"janhq/jan","slug":"mlx-engine-not-found","errorCode":null,"errorMessage":"MLX engine not found","messagePattern":"MLX engine not found","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"web-app/src/containers/MlxModelDownloadAction.tsx","lineNumber":136,"sourceCode":"        .fetchHuggingFaceRepo(modelPath, huggingfaceToken)\n\n      if (!repoInfo || !repoInfo.siblings) {\n        throw new Error('Failed to fetch repository files')\n      }\n\n      // Filter relevant model files for MLX\n      const modelFiles = repoInfo.siblings\n\n      if (modelFiles.length === 0) {\n        throw new Error('No MLX model files found in repository')\n      }\n\n      // Get the MLX engine and import\n      const engine = EngineManager.instance().get(\n        'mlx'\n      )\n      if (!engine) {\n        throw new Error('MLX engine not found')\n      }\n\n      // For MLX, we download the first safetensors file as the main model\n      // and the extension will download all related files\n      const mainSafetensorsFile = modelFiles.find((f) =>\n        f.rfilename.toLowerCase().endsWith('.safetensors')\n      )\n\n      if (!mainSafetensorsFile) {\n        throw new Error('No safetensors file found in repository')\n      }\n\n      const modelUrl = `https://huggingface.co/${modelPath}/resolve/main/${mainSafetensorsFile.rfilename}`\n\n      // Prepare additional files to download (all model files except main safetensors)\n      // Don't pass sha256/size to skip verification for MLX models\n      const extraFiles = modelFiles\n        .filter((f) => f.rfilename !== mainSafetensorsFile.rfilename)","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/janhq/jan/blob/fad3f12a147d138388a66f0d92a02b2675f65294/web-app/src/containers/MlxModelDownloadAction.tsx#L118-L154","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the app is running on Apple Silicon macOS (MLX requires Metal).","Enable/reinstall the MLX extension from settings and restart the app.","Check the extension's engine-registration log during startup for the exact key it uses.","Guard the download button so it is disabled when the MLX engine is not present."],"exampleFix":"// before\nconst engine = EngineManager.instance().get('mlx')\nif (!engine) {\n  throw new Error('MLX engine not found')\n}\n\n// after\nconst engine = EngineManager.instance().get('mlx')\nif (!engine) {\n  throw new Error(\n    'MLX engine not found. Install/enable the MLX extension (requires Apple Silicon macOS).'\n  )\n}","handlingStrategy":"type-guard","validationCode":"const engine = EngineManager.instance().get('mlx')\nif (!engine) {\n  toast.error('MLX unavailable', {\n    description: 'Install/enable the MLX extension (Apple Silicon required).',\n  })\n  return\n}","typeGuard":"function isMlxEngine(e: unknown): e is { import(id: string, opts: Record<string, unknown>): Promise<unknown> } {\n  return !!e && typeof (e as any).import === 'function'\n}","tryCatchPattern":"try {\n  const engine = EngineManager.instance().get('mlx')\n  if (!isMlxEngine(engine)) {\n    toast.error('MLX engine not found', { description: 'Apple Silicon + MLX extension required.' })\n    return\n  }\n  // proceed\n} catch (error) {\n  toast.error('Failed to download MLX model', { description: error instanceof Error ? error.message : String(error) })\n}","preventionTips":["Disable the Download button when getEngine('mlx') is null.","Gate MLX features to macOS Apple Silicon at the UI layer.","Log the registered engine keys at startup to catch key mismatches."],"tags":["mlx","engine","extension","platform"],"backgroundTag":null,"analyzedSha":"fad3f12a147d138388a66f0d92a02b2675f65294","analyzedAt":"2026-08-12T20:33:47.516Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}