PDF processing reports success but returns empty content

[ramarivera]

Bug Report: PDF Processing Returns Empty Content

Summary

DocStrange processes PDF successfully (reports "1 successful") but returns empty content for all output formats. The PDF is valid and readable by other tools.

Environment

• docstrange version: 1.1.5
• OS: macOS (Darwin)
• Python: (from mise/pipx installation)
• Authentication: Authenticated cloud mode (10k/month free calls)
• PDF details:
  • File: 2512.14012.pdf (likely arXiv paper)
  • Size: 1.4 MB
  • Pages: 11 (confirmed with file command)
  • Format: PDF 1.7

Steps to Reproduce

1. Basic markdown conversion (fails):

docstrange ~/Downloads/2512.14012.pdf --output markdown --verbose

Output:

Processing: /Users/ramarivera/Downloads/2512.14012.pdf

Summary: 1 successful, 0 failed
Initialized extractor in cloud mode:
  - Output format: markdown
  - Auth: authenticated (10k/month) free calls

[empty output]

2. JSON with field extraction (fails):

docstrange ~/Downloads/2512.14012.pdf --output json --extract-fields title abstract authors

Output:

{
  "document": {
    "raw_content": ""
  },
  "format": "json_parse_error",
  "error": "Expecting value: line 1 column 1 (char 0)"
}

3. With OCR enabled (fails):

docstrange ~/Downloads/2512.14012.pdf --output markdown --ocr-enabled --verbose

Still returns empty content.

4. With Gemini model (fails):

docstrange ~/Downloads/2512.14012.pdf --model gemini --output markdown --verbose

Still returns empty content.

5. Saving to file (fails):

docstrange ~/Downloads/2512.14012.pdf --output markdown --output-file output.md

Creates output.md with 0 bytes.

Expected Behavior

• Should extract text content from the PDF
• Should return markdown/JSON with the document content
• Should not report "successful" if content extraction failed

Actual Behavior

• Reports "1 successful" in summary
• Returns completely empty content (raw_content: "")
• No error messages or warnings about why extraction failed
• Output files are empty (0 bytes for markdown, error JSON for json format)

Additional Testing

✅ DocStrange works with simple text files:

echo "Test document" > test.txt
docstrange test.txt --output markdown

Returns:

# Text Document

Test document

❌ This specific PDF fails consistently

Tried all combinations of:

• Output formats: markdown, json, text, html
• Models: default (nanonets), gemini
• Flags: --ocr-enabled, --include-images, --preserve-layout
• All produce empty content

Possible Causes

1. Silent failure in PDF text extraction (no error logged)
2. Cloud API returning empty response without error
3. PDF might have embedded text that's not being detected
4. PDF might need OCR but OCR isn't triggering properly

Related Issues

• Issue Error getting json data "No content available" #48 mentions "No content available" for JSON extraction
• Issue Major Accuracy Difference Between Hosted OCR (docstrange.nanonets.com) and Downloaded Local Model #35 mentions accuracy differences between hosted vs local

Diagnostic Commands

# Verify PDF is valid
file 2512.14012.pdf
# Output: PDF document, version 1.7, 11 pages

# Check credentials
ls -la ~/.docstrange/credentials.json
# Exists and was created during authentication

# Test with verbose mode
docstrange 2512.14012.pdf --output json --verbose
# Shows successful authentication but empty content

Request

• Could you investigate why PDFs report "successful" but return empty content?
• Should there be more detailed error logging when extraction silently fails?
• Is there a way to get detailed debug logs to see what's happening during processing?

Sample File

The PDF that fails: 2512.14012.pdf (arXiv paper, 1.4MB, 11 pages)
I can provide the file if needed for debugging.

---

Note: Similar issues were searched before filing. This report was created with AI assistance.

[linear]

PLG-323

[ramarivera]

🔍 Root Cause Investigation Results

I investigated the codebase and found three critical issues causing this silent failure:

1. Silent Fallback to Empty String

Location: docstrange/processors/cloud_processor.py lines 44-120

When the cloud API fails for any reason (network error, timeout, 500 error, invalid response), the exception handler calls _convert_locally():

except Exception as e:
    logger.error(f"Failed to get {output_type} from cloud API: {e}")
    # Try fallback to local conversion for other errors
    return self._convert_locally(output_type)

Problem: _convert_locally() is non-functional for cloud results because it tries to convert self.content, which is initialized as an empty string "". The error is logged but not shown to users, resulting in silent failure.

2. Missing OCR Parameter

Location: docstrange/processors/cloud_processor.py line 56

The cloud API payload does not include the ocr_enabled, preserve_layout, or include_images flags:

data = {
    'output_type': output_type
}
# ocr_enabled is missing!

Even when users specify --ocr-enabled, this parameter is never sent to the cloud API. PDFs (especially scanned or complex ones) likely require ocr=True to extract any text.

Additional Issue: DocumentExtractor.__init__ (line 99-104 in extractor.py) doesn't pass ocr_enabled to the CloudProcessor constructor.

3. False Positive Success Reporting

Location: docstrange/cli.py lines 421-427

The CLI reports success immediately when extractor.extract() returns a result. In cloud mode, this happens instantly because CloudProcessor is lazy—it doesn't contact the API until output is requested. The CLI reports "successful scheduling" not "successful completion".

---

🛠️ Suggested Fixes

1. Add OCR parameter to API payload:

   data = {
       'output_type': output_type,
       'ocr_enabled': self.ocr_enabled,
       'preserve_layout': self.preserve_layout,
       'include_images': self.include_images
   }

2. Validate API response:

   content = response_data.get('content', '').strip()
   if not content:
       raise ConversionError("Cloud API returned empty content")

3. Fix or remove silent fallback:

   • Either raise the exception instead of falling back silently
   • Or implement real local fallback using PDFProcessor

4. Configure logging in CLI:

   • Add logging.basicConfig() when --verbose is used
   • This would make the logger.error messages visible to users

---

📋 Files to Review

• docstrange/processors/cloud_processor.py (CloudConversionResult class)
• docstrange/extractor.py (DocumentExtractor.init)
• docstrange/cli.py (success reporting logic)

---

❓ Questions

1. Does the cloud API expect ocr or ocr_enabled as the parameter name?
2. Should cloud results validate content immediately instead of being lazy?
3. Why is ocr_enabled omitted from the CloudProcessor constructor?

The investigation was performed on the codebase clone at commit main (latest).