Why Your Self-Hosted Stirling-PDF Container OOMs, Hangs or Returns a Broken PDF: 15 Anti-Patterns and Their Fixes

Description and use

Incorrect memory limits, image variant, OCR language packs, and temp file handling cause Stirling-PDF crashes. Setting memory limits, JVM heap, correct image, mounting language data, managing temp files, and extending proxy timeouts resolve the issues.

Problem

Self-hosted Stirling-PDF containers frequently crash, hang, or produce corrupted PDFs due to misconfigurations such as missing memory limits, incorrect image variants, inadequate OCR language packs, and improper temporary file handling.

Outcome

Properly configuring memory limits, JVM heap, image variants, OCR language packs, temporary file storage, and proxy timeouts eliminates OOM crashes, hangs, and corrupted PDFs, enabling reliable self-hosted Stirling-PDF deployments.

Workflow

• 1. Inspect container exit codes and logs to identify failure type.
• 2. Set a memory limit (e.g., 2–4 GB) and configure JVM heap with JAVA_TOOL_OPTIONS=-XX:MaxRAMPercentage=50.
• 3. Choose the correct image variant (latest, ultra-lite, or fat) based on required features.
• 4. Mount a volume at /usr/share/tessdata with needed language data for OCR.
• 5. Mount /tmp/stirling-pdf to a tmpfs or bind mount a directory to avoid overlay layer issues.
• 6. Configure temp file cleanup in /configs/settings.yml.
• 7. Adjust reverse proxy timeouts to exceed longest expected job duration.
• 8. Monitor docker stats during large jobs to verify resource usage.

Evidence

Docker applies no memory limit by default. A container-aware JVM with no -Xmx claims a maximum heap of 25 percent of the memory it can see, which is the host's total RAM when you set no limit.

Source

The UI still shows every button either way, which is why this fails so confusingly.

Source