danny-avila/LibreChat · error · Error

OCR capability is not enabled for Agents

Error message

OCR capability is not enabled for Agents

What it means

Thrown when `shouldUseConfiguredOCR` is true but `checkCapability(req, AgentCapabilities.ocr)` returns false. The OCR pipeline is opt-in (admin/tenant capability); if a file's MIME type routes to OCR but the capability is not enabled, the server refuses before calling the OCR service. This protects against billing an unaauthorized OCR call.

Source

Thrown at api/server/services/Files/process.js:850

          logger.error(
            `[processAgentFileUpload] Configured OCR failed for "${file.originalname}", falling back to document_parser:`,
            err,
          );
        }
      }
      try {
        const { handleFileUpload } = getStrategyFunctions(FileSources.document_parser);
        return await handleFileUpload({ req, file, loadAuthValues });
      } catch (err) {
        logger.error(
          `[processAgentFileUpload] Document parser failed for "${file.originalname}":`,
          err,
        );
      }
    };

    if (shouldUseConfiguredOCR && !(await checkCapability(req, AgentCapabilities.ocr))) {
      throw new Error('OCR capability is not enabled for Agents');
    }

    if (shouldUseOCR) {
      const ocrResult = await resolveDocumentText();
      if (ocrResult) {
        const { text, bytes, filepath: ocrFileURL } = ocrResult;
        return await createTextFile({ text, bytes, filepath: ocrFileURL });
      }
      throw new Error(
        `Unable to extract text from "${file.originalname}". The document may be image-based and requires an OCR service to process.`,
      );
    }

    const shouldUseSTT = fileConfig.checkType(
      file.mimetype,
      fileConfig.stt?.supportedMimeTypes || [],
    );

View on GitHub (pinned to 5ff282f900)

Solutions

1. Enable the ocr capability for the agent/tenant in admin settings.
2. Remove the relevant MIME types from the OCR supported list if OCR should stay off.
3. Frontend: warn users uploading image-based PDFs that OCR is not available for their agent.
4. Provide a text-version of the document instead of a scanned/image PDF.

async function assertOcrEnabled(req) {
  const ok = await checkCapability(req, AgentCapabilities.ocr);
  if (!ok) throw new Error('OCR capability is not enabled; cannot process image-only documents');
}

try { await processAgentFileUpload(params); }
catch (e) {
  if (/OCR capability is not enabled/.test(e.message)) return res.status(403).json({ error: e.message });
  throw e;
}

When it happens

Trigger: An image-only document (e.g., scanned PDF, JPEG of a receipt) is uploaded and the fileConfig routes its MIME to OCR (`shouldUseConfiguredOCR` true), but the agent/tenant does not have the ocr capability enabled.

Common situations: Admin added OCR MIME types to the config but never enabled the capability; cross-environment sync where the target env lacks the OCR entitlement; user uploads a scanned doc to an agent whose plan does not include OCR.

Related errors

• Code execution is not enabled for Agents
• File search is not enabled for Agents
• Unable to extract text from "${file.originalname}". The docu
• This tool is only available for agents.
• This tool is only available for agents.

AI-assisted analysis of danny-avila/LibreChat@5ff282f900 (2026-08-12). Data as JSON: /api/errors/7a537baf0ed3fab1. Report an issue: GitHub.