chatboxai/chatbox · error · OCRError

OCR Error (${ocrProvider}): ${cause.message}

Error message

OCR Error (${ocrProvider}): ${cause.message}

What it means

OCRError wraps a failure from ocrImagesInMessages. When the chosen model does not support vision (model.isSupportVision() false) but the prompt contains un-OCRed image parts, the harness routes images through an OCR provider as a fallback; if that OCR call throws, the underlying error is wrapped with the provider name so the UI can attribute and classify it. The class also re-maps Chatbox AI quota-exhausted causes into OCR-specific quota codes.

Source

Thrown at src/renderer/stores/session/agent-harness.ts:271

    maxContextMessageCount: settings.maxContextMessageCount,
    preserveToolCallMessageIds,
    sandboxMode: canExecuteCode,
  })

  const infoParts: MessageContentParts = []

  if (
    !model.isSupportVision() &&
    promptMsgs.some((message) => message.contentParts.some((part) => part.type === 'image' && !part.ocrResult))
  ) {
    const ocrResult = getOCRModel(globalSettings, configs, dependencies)
    if (!ocrResult) {
      throw ChatboxAIAPIError.fromCodeName('model_not_support_image_2', 'model_not_support_image_2')
    }
    try {
      await ocrImagesInMessages(promptMsgs, ocrResult.model)
    } catch (err) {
      throw new OCRError(ocrResult.providerName, err instanceof Error ? err : new Error(`${err}`))
    }
    infoParts.push({
      type: 'info',
      text: t('Current model {{modelName}} does not support image input, using OCR to process images', {
        modelName: model.modelId,
      }),
    })
  }

  const { promptMsgs: updatedMsgs, fallbackToolCallPart } = await applyLegacyToolFallback({
    model,
    promptMsgs,
    knowledgeBase,
    webBrowsing,
    signal,
  })
  promptMsgs = updatedMsgs

View on GitHub (pinned to 81571269ad)

Solutions

1. Switch to a vision-capable model (model.isSupportVision()) to bypass OCR entirely.
2. If using Chatbox AI OCR, check quota in Settings and upgrade or wait for the daily reset.
3. Validate image files before OCR (detect corruption, unsupported format, excessive size).
4. Handle OCRError by inspecting .code: quota codes warrant a quota message, OCR_FAILED warrants a generic retry.

Example fix

// before
try {
  await ocrImagesInMessages(promptMsgs, ocrResult.model)
} catch (err) {
  throw new OCRError(ocrResult.providerName, err instanceof Error ? err : new Error(`${err}`))
}
// after
try {
  await ocrImagesInMessages(promptMsgs, ocrResult.model)
} catch (err) {
  const cause = err instanceof Error ? err : new Error(`${err}`)
  throw new OCRError(ocrResult.providerName, cause)
}

const supportsVision = model.isSupportVision()
const needsOcr = !supportsVision && messagesHaveUnprocessedImages(promptMsgs)
if (needsOcr && !getOCRModel(globalSettings, configs, dependencies)) {
  throw ChatboxAIAPIError.fromCodeName('model_not_support_image_2', 'model_not_support_image_2')
}

function isOCRError(e: unknown): e is import('@shared/models/errors').OCRError {
  return e instanceof Error && (e as { ocrProvider?: unknown }).ocrProvider !== undefined
}

try {
  await runGeneration()
} catch (err) {
  if (err instanceof OCRError) {
    if (err.code === MESSAGE_ERROR_CODES.CHATBOX_AI_OCR_QUOTA_EXHAUSTED) showQuotaMessage()
    else showOcrFailedMessage(err.ocrProvider, err.cause.message)
  } else throw err
}

When it happens

Trigger: ocrImagesInMessages(promptMsgs, ocrResult.model) rejects. The cause is a network/transport failure to the OCR provider, a Chatbox AI quota exhaustion (token or free quota), a malformed/unsupported image, or the OCR model endpoint returning an error. ocrResult.providerName becomes the prefix.

Common situations: User attaches images to a text-only model with OCR fallback configured; OCR provider is Chatbox AI and the user is out of quota; the OCR model is misconfigured or its API key invalid; a corrupt image causes the OCR backend to error.

Related errors

• Invalid pagination parameters
• file is not an image
• Knowledge base ${kbId} not found
• Too many file IDs requested (max 100)
• Staged resource is missing: ${plan.resource.path}

AI-assisted analysis of chatboxai/chatbox@81571269ad (2026-08-12). Data as JSON: /api/errors/ca48c7caead8af8b. Report an issue: GitHub.