Why Your Self-Hosted Stirling-PDF Container OOMs, Hangs or Returns a Broken PDF: 15 Anti-Patterns and Their Fixes
Stirling-PDF is not an unstable application. Almost every crash, hang and quietly mangled output traces back to one of fifteen decisions you made outside the app: an unbounded container, the wrong image variant, a reverse proxy that gives up after 60 seconds, or an OCR call with no language pack behind it. The Java process inside the container claims a default heap of 25 percent of visible RAM,…
This article outlines fifteen common mistakes that lead to Stirling-PDF containers running out of memory (OOM), hanging or producing broken PDFs. The key culprits are:
1. Lack of a container memory limit
2. Not setting a Java heap size ceiling inside the container
3. Using the wrong image variant
4. Calling tools the container does not contain
For a typical home user with limited PDFs, a lightweight image with a hard 1GB container limit prevents most issues. More extensive setups need a full image, mounted language packs, and processing smaller batches to avoid OCR slowdowns. Automation builders should implement queues and timeout limits, while teams sharing an instance must budget for LibreOffice serialization.
Three failure types are distinguished by checking the exit code and container logs: OOM kills, OutOfMemoryErrors, and timeouts. Correcting the underlying issue requires setting appropriate memory limits, heap sizes, and timeouts. Diagnosing the wrong root cause wastes time.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
