{"record":{"id":"7a537baf0ed3fab1","repo":"danny-avila/LibreChat","slug":"ocr-capability-is-not-enabled-for-agents","errorCode":null,"errorMessage":"OCR capability is not enabled for Agents","messagePattern":"OCR capability is not enabled for Agents","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"api/server/services/Files/process.js","lineNumber":850,"sourceCode":"          logger.error(\n            `[processAgentFileUpload] Configured OCR failed for \"${file.originalname}\", falling back to document_parser:`,\n            err,\n          );\n        }\n      }\n      try {\n        const { handleFileUpload } = getStrategyFunctions(FileSources.document_parser);\n        return await handleFileUpload({ req, file, loadAuthValues });\n      } catch (err) {\n        logger.error(\n          `[processAgentFileUpload] Document parser failed for \"${file.originalname}\":`,\n          err,\n        );\n      }\n    };\n\n    if (shouldUseConfiguredOCR && !(await checkCapability(req, AgentCapabilities.ocr))) {\n      throw new Error('OCR capability is not enabled for Agents');\n    }\n\n    if (shouldUseOCR) {\n      const ocrResult = await resolveDocumentText();\n      if (ocrResult) {\n        const { text, bytes, filepath: ocrFileURL } = ocrResult;\n        return await createTextFile({ text, bytes, filepath: ocrFileURL });\n      }\n      throw new Error(\n        `Unable to extract text from \"${file.originalname}\". The document may be image-based and requires an OCR service to process.`,\n      );\n    }\n\n    const shouldUseSTT = fileConfig.checkType(\n      file.mimetype,\n      fileConfig.stt?.supportedMimeTypes || [],\n    );\n","sourceCodeStart":832,"sourceCodeEnd":868,"githubUrl":"https://github.com/danny-avila/LibreChat/blob/5ff282f9006c436e561de1afd39a481bea1ef0d8/api/server/services/Files/process.js#L832-L868","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Enable the ocr capability for the agent/tenant in admin settings.","Remove the relevant MIME types from the OCR supported list if OCR should stay off.","Frontend: warn users uploading image-based PDFs that OCR is not available for their agent.","Provide a text-version of the document instead of a scanned/image PDF."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"async function assertOcrEnabled(req) {\n  const ok = await checkCapability(req, AgentCapabilities.ocr);\n  if (!ok) throw new Error('OCR capability is not enabled; cannot process image-only documents');\n}","typeGuard":null,"tryCatchPattern":"try { await processAgentFileUpload(params); }\ncatch (e) {\n  if (/OCR capability is not enabled/.test(e.message)) return res.status(403).json({ error: e.message });\n  throw e;\n}","preventionTips":["Enable the ocr capability before adding OCR MIME types to fileConfig.","Frontend: warn users uploading image-only PDFs when OCR is off.","Keep capability flags and MIME routing in sync across config changes."],"tags":["agent","capability","ocr","authorization"],"backgroundTag":null,"analyzedSha":"5ff282f9006c436e561de1afd39a481bea1ef0d8","analyzedAt":"2026-08-12T21:38:08.145Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}