Skill v1.0.2
Automated scan100/1001 files
version: "1.0.2" name: pdftotext-fallback description: Recover PDF text extraction when read_file returns binary data by using pdftotext via shell
pdftotext Fallback for PDF Text Extraction
When to Use
Apply this pattern when:
read_fileon a PDF returns binary/image data instead of readable text- Python-based PDF extraction (PyMuPDF, pdfplumber, etc.) in
execute_code_sandboxfails or returns garbled content - You need reliable text extraction from PDF files as a recovery strategy
Why This Works
The pdftotext utility (from poppler-utils) is a mature, command-line tool that handles many PDF edge cases that confuse Python libraries or the read_file tool. It's pre-installed on most Linux systems and provides consistent, reliable text extraction.
Steps
Step 1: Detect the Failure
Recognize extraction failure when:
read_filereturns binary content, image data, or garbled text- Error messages indicate encoding issues or unsupported formats
- Python PDF libraries in sandbox fail with import errors or extraction failures
Step 2: Use pdftotext via run_shell
Extract to stdout (recommended for quick extraction):
pdftotext /path/to/file.pdf -
The - argument outputs directly to stdout for easy capture in your tool response.
Example:
run_shell("pdftotext document.pdf -")
Step 3: Handle Complex PDFs
Preserve layout (maintains original formatting):
pdftotext -layout /path/to/file.pdf -
Extract to a file (for large PDFs):
pdftotext /path/to/file.pdf /path/to/output.txt
Then read the output file with read_file.
Handle encoded text:
pdftotext -enc UTF-8 /path/to/file.pdf -
Step 4: Verify and Continue
- Check the extracted text for completeness
- If text is still garbled, the PDF may be image-based (scanned) - consider OCR tools
- Proceed with your task using the extracted text
Code Examples
Basic extraction:
# Simple text extractiontext = run_shell("pdftotext document.pdf -")
With error handling:
# Try extraction, check for successresult = run_shell("pdftotext document.pdf - && echo 'SUCCESS' || echo 'FAILED'")
Multi-page PDF with layout:
# Preserve tables and formattingtext = run_shell("pdftotext -layout document.pdf -")
Troubleshooting
| Issue | Solution | |
|---|---|---|
pdftotext: command not found | Install poppler-utils: apt-get install poppler-utils | |
| Garbled/special characters | Try -enc UTF-8 or -enc ASCII7 | |
| Missing formatting | Use -layout flag | |
| Scanned PDF (no text) | Requires OCR (e.g., tesseract), not text extraction | |
| Large PDF timeout | Extract to file instead of stdout |
Limitations
- Does not work on image-only (scanned) PDFs without embedded text
- May lose complex formatting, tables, or embedded objects
- Requires poppler-utils to be installed (common on Linux, may need installation on other systems)
Related Tools
pdfinfo: Get PDF metadata (pages, size, etc.)pdftoppm: Convert PDF pages to imagestesseract: OCR for scanned PDFs