{"record":{"id":"4f1e2d1c3be3c4a3","repo":"danny-avila/LibreChat","slug":"unable-to-extract-text-from-file-originalname","errorCode":null,"errorMessage":"Unable to extract text from \"${file.originalname}\". The document may be image-based and requires an OCR service to process.","messagePattern":"Unable to extract text from \"(.+?)\"\\. The document may be image-based and requires an OCR service to process\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"api/server/services/Files/process.js","lineNumber":859,"sourceCode":"      } 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\n    if (shouldUseSTT) {\n      const sttService = await STTService.getInstance();\n      const { text, bytes } = await processAudioFile({ req, file, sttService });\n      return await createTextFile({ text, bytes });\n    }\n\n    const shouldUseText = fileConfig.checkType(\n      file.mimetype,\n      fileConfig.text?.supportedMimeTypes || [],","sourceCodeStart":841,"sourceCodeEnd":877,"githubUrl":"https://github.com/danny-avila/LibreChat/blob/5ff282f9006c436e561de1afd39a481bea1ef0d8/api/server/services/Files/process.js#L841-L877","documentation":"Thrown when `shouldUseOCR` is true and the OCR/document-parser resolver (`resolveDocumentText`) returned a falsy result (null/undefined). This means neither the configured OCR service nor the built-in document parser could extract any text from the file — typically because the document is image-based and no OCR backend produced usable output.","triggerScenarios":"A pure-image PDF or raster document where the OCR service returned empty/failed silently and the built-in document parser (FileSources.document_parser) also produced nothing. The catch block in resolveDocumentText swallows parser errors and returns undefined, which this guard surfaces as a single message.","commonSituations":"Scanned PDFs with no text layer where OCR is unavailable, misconfigured, or rate-limited; corrupt images; OCR service credentials invalid (silent failure inside resolveDocumentText); a parser version that does not handle the file's encoding.","solutions":["Enable and configure an OCR backend capable of handling the file's language/content.","Provide a text-based version of the document (selectable-text PDF, DOCX, TXT) instead of an image scan.","Inspect server logs for the `[processAgentFileUpload] Document parser failed for ...` line — that holds the underlying OCR/parser error.","Verify OCR service credentials and connectivity if using a remote OCR provider."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { await processAgentFileUpload(params); }\ncatch (e) {\n  if (/requires an OCR service/.test(e.message)) {\n    return res.status(422).json({ error: 'Could not extract text. Upload a selectable-text version or contact an admin about OCR.' });\n  }\n  throw e;\n}","preventionTips":["Prefer selectable-text PDFs/DOCX over scanned images.","Keep the OCR backend healthy and its credentials current; check logs for parser failures.","Surface the underlying OCR error from logs rather than retrying blindly."],"tags":["ocr","document","text-extraction","agent"],"backgroundTag":null,"analyzedSha":"5ff282f9006c436e561de1afd39a481bea1ef0d8","analyzedAt":"2026-08-12T21:38:08.145Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}