Why is my converted PDF different between staging and production?

There are a few common reasons a “converted PDF” can differ between staging and production, even when the source file is the same:

1) Different conversion engine versions

If staging and production use different versions of:

• LibreOffice / OpenOffice
• wkhtmltopdf
• Chromium / Playwright / Puppeteer
• a PDF library like iText, PDFBox, Ghostscript

…then layout, fonts, pagination, and image rendering can change.

2) Font differences

PDF output is very sensitive to available fonts.

• A missing font may be substituted differently in each environment.
• Font rendering and embedding can vary.
• Even minor font metric differences can shift line breaks and page breaks.

3) OS / system library differences

Different:

• Linux distro versions
• libc / freetype / fontconfig versions
• Docker base images
• locale settings

can all affect text shaping, hyphenation, and layout.

4) HTML/CSS or rendering environment mismatch

If the PDF is generated from HTML:

• browser engine differences matter
• CSS support may differ
• media queries may resolve differently
• page size/margins may be affected by print settings

5) Resource loading differences

Staging and production may load different:

• images
• CSS
• JS
• remote assets
• API data

for example due to different URLs, auth, caching, or environment variables.

6) Time, locale, and data differences

Generated PDFs may include:

• timestamps
• date formatting
• number formatting
• language/locale-specific text

These can change output or line wrapping.

7) Concurrency / race conditions

If PDF generation depends on temp files, caching, or shared state, production load can cause intermittent differences.

8) Permissions or sandbox differences

If the converter can’t access certain assets in one environment, it may silently fall back or omit content.

---

What to check first

1. Compare exact converter versions in staging vs prod.
2. Compare installed fonts.
3. Compare OS/base image and library versions.
4. Check whether both environments are loading the same input and assets.
5. Compare locale/timezone.
6. Diff the generated PDFs with a tool that extracts text/metadata/layout.

---

Practical debugging steps

• Log converter version and command-line flags.
• Hash and archive the exact input files and referenced assets.
• Run the same container/image in both places if possible.
• Use font embedding or bundle fonts explicitly.
• Pin the Docker image and dependencies.
• Generate a minimal test document to isolate the issue.

If you want, I can help you build a short checklist or troubleshoot a specific converter stack like wkhtmltopdf, LibreOffice, or Chromium/Playwright.