Skip to content

troubleshooting.md

Latest commit

 

History

History
285 lines (214 loc) · 5.88 KB

troubleshooting.md

File metadata and controls

285 lines (214 loc) · 5.88 KB
Raw

Troubleshooting Guide

Common Issues

1. "pdftoppm not found" or "Unable to get page count"

Cause: Poppler is not installed or not in your PATH.

Solution:

# macOS
brew install poppler

# Ubuntu/Debian
sudo apt-get install poppler-utils

# Fedora/RHEL
sudo dnf install poppler-utils

Verify installation:

pdftoppm -v

2. "No module named 'PIL'"

Cause: Pillow is not installed.

Solution:

pip install Pillow

3. "No module named 'pdf2image'"

Cause: pdf2image is not installed.

Solution:

pip install pdf2image

4. "Input file not found"

Cause: The input file path is incorrect or the file doesn't exist.

Solution:

  • Check the file path is correct
  • Use absolute paths if relative paths aren't working
  • Ensure you have read permissions for the file
# Use absolute path
python3 securecompress_cli.py --input /full/path/to/input.pdf --output output.pdf --size 5

5. "Permission denied" when writing output

Cause: No write permission in the output directory.

Solution:

  • Check directory permissions
  • Try writing to a different directory
  • Use a directory you own
# Write to home directory
python3 securecompress_cli.py --input input.pdf --output ~/output.pdf --size 5

6. Output file is larger than target

Cause: The PDF cannot be compressed to the target size without severe quality loss.

Solutions:

  • Increase the target size
  • Use more aggressive settings: 
    python3 securecompress_cli.py \
  --input input.pdf \
  --output output.pdf \
  --size 5 \
  --dpi 120 \
  --mode gray \
  --max-passes 4
  • Use black and white mode for text documents: 
    --mode bw

7. "Out of memory" or process killed

Cause: Insufficient RAM for processing large PDFs.

Solutions:

  • Close other applications
  • Process smaller PDFs
  • Use lower DPI: 
    --dpi 120
  • Split the PDF into smaller parts and process separately

8. Very slow processing

Cause: High DPI, many pages, or multiple passes.

Solutions:

  • Reduce DPI: 
    --dpi 150
  • Reduce max passes: 
    --max-passes 1
  • Disable quality check: 
    # Don't use --quality-check
  • Use object engine for text documents: 
    --engine object --content-type text

9. Poor output quality

Cause: Too aggressive compression settings.

Solutions:

  • Increase target size
  • Increase DPI: 
    --dpi 250
  • Enable quality check: 
    --quality-check --quality-threshold 0.85
  • Use adaptive compression: 
    --adaptive
  • Use color mode instead of grayscale: 
    --mode color

10. "Failed to read PDF info"

Cause: The PDF is corrupted, encrypted, or not a valid PDF.

Solutions:

  • Verify the file is a valid PDF
  • Try opening it in a PDF reader
  • If encrypted, decrypt it first
  • Try repairing the PDF with another tool

11. Some pages failed to process

Cause: Certain pages have issues or are too complex.

What happens: The CLI will skip failed pages and continue with others.

Solutions:

  • Check the summary for failed_pages list
  • Try with different settings
  • Extract and process failed pages separately
  • Consider using the GUI version for better error handling

12. Temporary files not cleaned up

Cause: Process was killed forcefully or crashed.

Solution:

# Manually remove temporary directories
rm -rf sc_temp_frames_pass*

13. "Ghostscript not found" warning

Cause: Ghostscript is not installed (optional dependency).

Impact: Object-level compression won't be available, but raster compression will still work.

Solution (optional):

# macOS
brew install ghostscript

# Ubuntu/Debian
sudo apt-get install ghostscript

# Fedora/RHEL
sudo dnf install ghostscript

14. JSON parsing errors in integration

Cause: Mixing JSON output with other print statements.

Solution: Only parse lines that are valid JSON:

for line in process.stdout:
    try:
        data = json.loads(line.strip())
        # Process data
    except json.JSONDecodeError:
        # Skip non-JSON lines
        continue

15. Process hangs or freezes

Cause: Very large page or complex graphics.

Solutions:

  • Wait longer (some pages take time)
  • Use Ctrl+C to cancel gracefully
  • Reduce DPI
  • Try with --engine object

Getting Help

If you're still having issues:

  1. Check the documentation:

  2. Search existing issues:

  3. Create a new issue:

    • Include your OS and Python version
    • Include the full command you ran
    • Include the error message
    • Include a sample PDF if possible (or describe it)

  4. Consider the GUI version:

Debug Mode

For detailed debugging information, use the --log option:

python3 securecompress_cli.py \
  --input input.pdf \
  --output output.pdf \
  --size 5 \
  --log debug.log

Then check debug.log for detailed information about what went wrong.

System Requirements

Minimum:

  • Python 3.7+
  • 2GB RAM
  • 1GB free disk space
  • Poppler installed

Recommended:

  • Python 3.9+
  • 4GB+ RAM
  • 5GB+ free disk space
  • Poppler and Ghostscript installed

Known Limitations

  1. Free version limits: 25MB input, 20 pages maximum
  2. PDF features: May lose forms, annotations, JavaScript, etc.
  3. Encrypted PDFs: Cannot process password-protected PDFs
  4. Memory usage: Large pages require significant RAM
  5. Processing time: Large PDFs can take several minutes

For unlimited processing and advanced features, consider QuantPDF Pro: https://quantpdf.com