danny-avila/LibreChat · warning · Error

Unable to extract text from "${file.originalname}". The docu

Error message

Unable to extract text from "${file.originalname}". The document may be image-based and requires an OCR service to process.

What it means

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.

Source

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

      } 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 || [],
    );

    if (shouldUseSTT) {
      const sttService = await STTService.getInstance();
      const { text, bytes } = await processAudioFile({ req, file, sttService });
      return await createTextFile({ text, bytes });
    }

    const shouldUseText = fileConfig.checkType(
      file.mimetype,
      fileConfig.text?.supportedMimeTypes || [],

View on GitHub (pinned to 5ff282f900)

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.

Defensive patterns

Strategy: fallback

Try / catch

try { await processAgentFileUpload(params); }
catch (e) {
  if (/requires an OCR service/.test(e.message)) {
    return res.status(422).json({ error: 'Could not extract text. Upload a selectable-text version or contact an admin about OCR.' });
  }
  throw e;
}

Prevention

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.

When it happens

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

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

Related errors

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