---
name: pdf-read-file-fallback-4ca305d69f89
description: Extract text from PDFs using pdftotext when read_file returns binary data
---

# PDF Text Extraction Fallback

## When to Use

Use this pattern when `read_file` with `filetype="pdf"` returns binary image data instead of extractable text content. This commonly occurs with PDFs that contain scanned images or complex formatting.

## Steps

### 1. Attempt Primary Extraction

First, try using `read_file`:

```python
result = read_file(file_path="document.pdf", filetype="pdf")
```

**Important**: Use `filetype` (not `file_type`) - incorrect parameter naming will cause execution failures.

### 2. Detect Binary/Image Data

Check if the result contains unusable content:

```python
# Indicators of binary/image data:
# - Contains null bytes: '\x00'
# - Very short or empty
# - Contains image markers (PNG/JPEG headers)
# - Unreadable character sequences

if not result or len(result) < 50 or '\x00' in str(result):
    # Proceed to fallback
```

### 3. Use pdftotext via run_shell

Extract text using the `pdftotext` command-line tool:

```python
shell_result = run_shell(command="pdftotext -layout document.pdf -")
text_content = shell_result.stdout
```

The `-` flag outputs to stdout for easy capture. The `-layout` flag preserves original formatting.

### 4. Handle pdftotext Unavailable

If `pdftotext` is not installed, try Python-based extraction:

```python
result = execute_code_sandbox(code="""
import pdfplumber
text = ''
with pdfplumber.open('document.pdf') as pdf:
    for page in pdf.pages:
        extracted = page.extract_text()
        if extracted:
            text += extracted + '\\n'
print(text)
""")
```

## Complete Example

```python
file_path = "report.pdf"

# Primary attempt
result = read_file(file_path=file_path, filetype="pdf")

# Validate and fallback if needed
if not result or len(str(result)) < 100 or '\x00' in str(result):
    # Fallback to pdftotext
    shell_result = run_shell(command=f"pdftotext -layout {file_path} -")
    text_content = shell_result.stdout
    
    # If pdftotext fails, try Python extraction
    if not text_content or len(text_content) < 50:
        code_result = execute_code_sandbox(code=f"""
import pdfplumber
text = ''
with pdfplumber.open('{file_path}') as pdf:
    for page in pdf.pages:
        extracted = page.extract_text()
        if extracted:
            text += extracted + '\\n'
print(text)
""")
        text_content = code_result
```

## Notes

- `pdftotext` is part of the `poppler-utils` package on most Linux systems
- For scanned/image-only PDFs, consider OCR tools (tesseract) instead
- Always validate parameter names against tool documentation (`filetype` vs `file_type`)

---
Source attribution: AG064
Original project: https://github.com/AG064/OpenSpace/blob/ff671ef61ed6587c49bd54c81cdc751c0b99e363/gdpval_bench/skills/pdf-read-file-fallback/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2026 ✨Data Intelligence Lab@HKU✨

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: AG064
Original project: https://github.com/AG064/OpenSpace/blob/ff671ef61ed6587c49bd54c81cdc751c0b99e363/gdpval_bench/skills/pdf-read-file-fallback/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Development & Engineering
Roles: Backend Developer, Data Analyst, Data Scientist
Specialties: API, Backend, Cross Platform
Tools: Pdfplumber, Pdftotext
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 40fbe40eac29758be2bd63fa5d6c616cf6b5d0e4c6a8db13a8b702af001661fd