janhq/jan · error · Error

model-errors:startModelFailed

model-errors:startModelFailed

Error message

model-errors:startModelFailed

What it means

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

Source

Thrown at web-app/src/lib/model-factory.ts:920

  private static async createLlamaCppModel(
    modelId: string,
    provider?: ProviderObject,
    parameters: Record<string, unknown> = {}
  ): Promise<LanguageModel> {
    // Start the model first if provider is available
    if (provider) {
      try {
        const { useServiceStore } = await import('@/hooks/useServiceHub')
        const serviceHub = useServiceStore.getState().serviceHub

        if (serviceHub) {
          await serviceHub.models().startModel(provider, modelId)
        }
      } catch (error) {
        console.error('Failed to start llamacpp model:', error)
        // A serialized engine error is a plain object, so the previous
        // `instanceof Error` path stringified it into raw JSON for the user.
        throw new Error(
          i18n.t('model-errors:startModelFailed', {
            reason: describeEngineError(error),
          })
        )
      }
    }

    // Get session info which includes port and api_key
    const sessionInfo = await invoke<SessionInfo | null>(
      'plugin:llamacpp|find_session_by_model',
      { modelId }
    )

    if (!sessionInfo) {
      throw new Error(
        i18n.t('model-errors:noRunningSession', { model: modelId })
      )
    }

View on GitHub (pinned to fad3f12a14)

Solutions

1. 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.
2. If out of memory: lower n_gpu_layers / ctx_len in the model's advanced settings, or pick a smaller quant.
3. If the file is missing/corrupt: re-download the model from the catalog and delete the partial file first.
4. Update or reinstall the @janhq/llamacpp-extension and the bundled llama.cpp binary to match the GGUF's version.
5. On GPU errors, verify driver/CUDA Toolkit/Metal support and that device selection in Settings matches available hardware.

Example fix

// before
await serviceHub.models().startModel(provider, modelId)
// after: pre-flight the model file before starting, so the error names the real problem
const info = await serviceHub.models().getModel(modelId)
if (!info?.file_path || !(await pathExists(info.file_path))) {
  throw new Error(`Model file missing on disk: ${modelId}. Re-download it from the Hub.`)
}
await serviceHub.models().startModel(provider, modelId)

async function canStartModel(modelsService, provider, modelId): Promise<boolean> {
  const info = await modelsService.getModel(modelId)
  return Boolean(info?.file_path)
}
// before startModel:
if (!(await canStartModel(serviceHub.models(), provider, modelId))) {
  throw new Error(`Model file missing for ${modelId}`)
}

function isEngineError(e: unknown): e is { message: string; code?: string } {
  return typeof e === 'object' && e !== null && 'message' in e && typeof (e as any).message === 'string'
}

try {
  await serviceHub.models().startModel(provider, modelId)
} catch (error) {
  throw new Error(i18n.t('model-errors:startModelFailed', { reason: describeEngineError(error) }))
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• model-errors:noRunningSession
• No running MLX session found for model: ${modelId}
• llamacpp extension not found
• Router failed its health check on backend ${targetBackendStr
• String length {} is unreasonably large

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