{"record":{"id":"fd849b9d643d414a","repo":"janhq/jan","slug":"model-errors-startmodelfailed","errorCode":"model-errors:startModelFailed","errorMessage":"model-errors:startModelFailed","messagePattern":"model-errors:startModelFailed","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"web-app/src/lib/model-factory.ts","lineNumber":920,"sourceCode":"  private static async createLlamaCppModel(\n    modelId: string,\n    provider?: ProviderObject,\n    parameters: Record<string, unknown> = {}\n  ): Promise<LanguageModel> {\n    // Start the model first if provider is available\n    if (provider) {\n      try {\n        const { useServiceStore } = await import('@/hooks/useServiceHub')\n        const serviceHub = useServiceStore.getState().serviceHub\n\n        if (serviceHub) {\n          await serviceHub.models().startModel(provider, modelId)\n        }\n      } catch (error) {\n        console.error('Failed to start llamacpp model:', error)\n        // A serialized engine error is a plain object, so the previous\n        // `instanceof Error` path stringified it into raw JSON for the user.\n        throw new Error(\n          i18n.t('model-errors:startModelFailed', {\n            reason: describeEngineError(error),\n          })\n        )\n      }\n    }\n\n    // Get session info which includes port and api_key\n    const sessionInfo = await invoke<SessionInfo | null>(\n      'plugin:llamacpp|find_session_by_model',\n      { modelId }\n    )\n\n    if (!sessionInfo) {\n      throw new Error(\n        i18n.t('model-errors:noRunningSession', { model: modelId })\n      )\n    }","sourceCodeStart":902,"sourceCodeEnd":938,"githubUrl":"https://github.com/janhq/jan/blob/fad3f12a147d138388a66f0d92a02b2675f65294/web-app/src/lib/model-factory.ts#L902-L938","documentation":"Thrown by createLlamaCppModel when serviceHub.models().startModel(provider, modelId) rejects while booting a local llama.cpp engine. The catch wraps the underlying cause through describeEngineError (which handles serialized engine objects that are not Error instances) and surfaces an i18n-localized 'model-errors:startModelFailed' message with the reason (model-factory.ts:920).","triggerScenarios":"Selecting a local GGUF model whose startModel() call throws: missing or corrupted model file, unsupported GGUF version, insufficient RAM/VRAM, requested GPU layers exceed available devices, context size too large, or the llama.cpp sidecar process crashed during init.","commonSituations":"Model download interrupted leaving a truncated file; user picked a quant their GPU cannot fit; CUDA/Metal driver mismatch after an OS update; antivirus quarantined the sidecar binary; wrong chat template / tokenizer files alongside the GGUF.","solutions":["Read the 'reason' in the surfaced message and the matching console.error('Failed to start llamacpp model') — the engine error (OOM, 'model file not found', CUDA error) names the real cause.","If out of memory: lower n_gpu_layers / ctx_len in the model's advanced settings, or pick a smaller quant.","If the file is missing/corrupt: re-download the model from the catalog and delete the partial file first.","Update or reinstall the @janhq/llamacpp-extension and the bundled llama.cpp binary to match the GGUF's version.","On GPU errors, verify driver/CUDA Toolkit/Metal support and that device selection in Settings matches available hardware."],"exampleFix":"// before\nawait serviceHub.models().startModel(provider, modelId)\n// after: pre-flight the model file before starting, so the error names the real problem\nconst info = await serviceHub.models().getModel(modelId)\nif (!info?.file_path || !(await pathExists(info.file_path))) {\n  throw new Error(`Model file missing on disk: ${modelId}. Re-download it from the Hub.`)\n}\nawait serviceHub.models().startModel(provider, modelId)","handlingStrategy":"try-catch","validationCode":"async function canStartModel(modelsService, provider, modelId): Promise<boolean> {\n  const info = await modelsService.getModel(modelId)\n  return Boolean(info?.file_path)\n}\n// before startModel:\nif (!(await canStartModel(serviceHub.models(), provider, modelId))) {\n  throw new Error(`Model file missing for ${modelId}`)\n}","typeGuard":"function isEngineError(e: unknown): e is { message: string; code?: string } {\n  return typeof e === 'object' && e !== null && 'message' in e && typeof (e as any).message === 'string'\n}","tryCatchPattern":"try {\n  await serviceHub.models().startModel(provider, modelId)\n} catch (error) {\n  throw new Error(i18n.t('model-errors:startModelFailed', { reason: describeEngineError(error) }))\n}","preventionTips":["Pre-flight that the model file exists on disk and is non-truncated before starting.","Cap n_gpu_layers / ctx_len based on detected VRAM/RAM to avoid OOM at start.","Keep the llama.cpp extension and runtime version aligned with the GGUF files you download.","Log describeEngineError output so OOM vs missing-file vs GPU errors are distinguishable."],"tags":["llamacpp","local-model","engine","gpu","memory","typescript","i18n"],"backgroundTag":null,"analyzedSha":"fad3f12a147d138388a66f0d92a02b2675f65294","analyzedAt":"2026-08-12T20:33:47.516Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}