Short answer: treat a PDF preview timeout as a render-budget problem first. Measure page count, pixel dimensions, and per-page time, then cap resolution or split the job before changing the timeout. For a B2B SaaS invoice preview, this keeps the fast path predictable while sending unusually large documents to an explicit review path.
A preview is a product feature, not a tiny export job. A 12-page invoice packet at 300 DPI can require far more raster work than a 2-page invoice at 96 DPI, even when both uploads are only a few megabytes. The useful diagnostic is therefore a tuple: (pages, target_dpi, output_pixels, elapsed_ms).
What should you measure before changing a PDF preview timeout?
Start with facts from the input and from the renderer. Do not infer page count from file size. A compressed PDF may contain a single page with a huge embedded image, while a text-heavy 80-page document can be small. Record the PDF byte size, page count, requested DPI, calculated pixel bounds, output format, and a correlation ID.
The following Python sketch uses a generic renderer interface. inspect_pdf and render_page stand in for the library already approved by your application; the control flow is the part worth keeping.
from dataclasses import dataclass
from time import monotonic
from typing import Protocol
class PdfRenderer(Protocol):
def page_count(self, pdf_bytes: bytes) -> int: ...
def render_page(self, pdf_bytes: bytes, page_number: int, dpi: int) -> bytes: ...
@dataclass
class PreviewMetrics:
pages: int
dpi: int
elapsed_ms: int
output_bytes: int
def render_preview(pdf_bytes: bytes, renderer: PdfRenderer, dpi: int = 144) -> tuple[list[bytes], PreviewMetrics]:
started = monotonic()
pages = renderer.page_count(pdf_bytes)
if pages < 1:
raise ValueError("PDF has no renderable pages")
if pages > 40:
raise ValueError("Preview requires an asynchronous review path")
images: list[bytes] = []
for page_number in range(1, pages + 1):
images.append(renderer.render_page(pdf_bytes, page_number, dpi))
elapsed_ms = round((monotonic() - started) * 1000)
metrics = PreviewMetrics(pages, dpi, elapsed_ms, sum(map(len, images)))
return images, metrics
That page cap is an application policy, not a PDF standard. Pick it from your latency objective and test corpus. Make the policy visible and measurable. A timeout should be the last line of defense, not the first diagnostic knob.
Small clue: page count is cheap to measure.
How do page count and resolution multiply render cost?
Raster work grows with page area. For a page that is width_in by height_in inches, the approximate pixel count is (width_in * dpi) * (height_in * dpi). Doubling DPI doubles each dimension and roughly quadruples pixels. Rendering every page then multiplies that cost by page count.
For example, a US Letter page at 144 DPI is about 1,224 by 1,584 pixels, or roughly 1.9 million pixels before color channels and compression. At 288 DPI it is about 4 times that area. Ten pages at the higher setting can saturate CPU and memory even if the final JPEGs are aggressively compressed.
This is where invoice previews often go wrong: a customer uploads a packet with a cover sheet, terms, and appendices, while the UI only needs the first page and a thumbnail strip. Rendering all pages at print resolution spends the budget on pixels nobody sees.
Use two budgets. The interactive budget limits the first visible page, such as 2 seconds in your service-level objective. The batch budget covers the remaining pages and can run asynchronously. Keep the numbers in configuration so an evaluation harness can sweep them. I am not sure which DPI will look right for your fonts and barcode mix; your mileage may vary, so compare representative PDFs rather than trusting a universal preset.
A practical policy looks like this:
from dataclasses import dataclass
@dataclass(frozen=True)
class RenderPolicy:
first_page_dpi: int = 144
thumbnail_dpi: int = 72
max_interactive_pages: int = 3
max_pixels_per_page: int = 3_000_000
def choose_dpi(width_in: float, height_in: float, requested_dpi: int, policy: RenderPolicy) -> int:
requested_pixels = width_in * height_in * requested_dpi * requested_dpi
if requested_pixels <= policy.max_pixels_per_page:
return requested_dpi
scale = (policy.max_pixels_per_page / (width_in * height_in)) ** 0.5
return max(36, min(requested_dpi, int(scale)))
The fallback is explicit: lower the raster resolution when the pixel budget would be exceeded, and tell the caller which policy was applied. Do not silently claim that a low-resolution thumbnail is the archival image.
Which failure modes make a timeout look like a page-count bug?
A timeout can be caused by input structure, not just a slow renderer. Encrypted files may require a password. A malformed cross-reference table can trigger expensive recovery work. A page with a large transparency group or embedded photograph can dominate the whole job. Fonts can also change output size and raster time. Capture these as dimensions in logs.
I once started by raising a worker timeout from 10 seconds to 60. The error rate fell, but the queue became harder to drain because a few pathological files occupied workers. Looking at the trace made the pattern obvious: ordinary two-page invoices finished quickly, while one scanned packet spent nearly the whole minute on a single high-resolution page. Raising the limit had hidden that distribution from the alert rather than improving the renderer. The useful fix was to separate admission from rendering: inspect page count and declared limits synchronously, render the first page under a deadline, and enqueue the rest with a bounded retry count.
The timeout was only the symptom.
Do not retry every timeout. If the same input, page, and DPI exceed the deadline twice, mark the preview as needs_review and preserve the correlation ID. A retry is useful for transient worker pressure; it is wasteful for deterministic pixel overload.
For each attempt, emit structured fields like pdf_sha256, pages, page_number, dpi, pixel_budget, elapsed_ms, worker_id, and outcome. Avoid logging invoice contents. These fields let you build a histogram of page-level time instead of arguing from a single request trace.
How can a Python preview worker stay predictable under load?
Use a small admission function before the expensive call. It should reject impossible work with a clear status, reserve memory proportional to the pixel budget, and keep cancellation visible to the queue. The renderer process should have an OS-level memory limit where practical; a Python exception alone cannot protect the host from native decoder allocations.
The worker below shows the decision boundaries without assuming a particular queue or PDF library.
from dataclasses import dataclass
@dataclass(frozen=True)
class PreviewRequest:
pdf_bytes: bytes
pages: int
dpi: int
def admit(request: PreviewRequest, policy: RenderPolicy) -> str:
if request.pages <= 0:
return "invalid"
if request.pages > 40:
return "async_review"
if request.dpi > 300:
return "lower_dpi"
if request.pages > policy.max_interactive_pages:
return "first_page_now"
return "render_now"
Keep an eval set of invoices with known page counts, rotated pages, scans, vector-heavy charts, and embedded barcodes. For each candidate policy, measure first-image latency, full-preview latency, peak resident memory, and visual fidelity. Token cost matters in my AI features, and the same discipline applies here: measure the expensive unit, then choose the smallest output that answers the user’s immediate question.
When is a lower-resolution preview the wrong choice?
The catch is fidelity. A 72 DPI thumbnail is fine for navigation but unsuitable for reading a tax identifier or validating a barcode. A first-page-only policy is unsuitable when users must inspect every line before approval. In those cases, stick with full-page rendering or offer a download of the original PDF, and make the slower path asynchronous with progress.
A vendor-neutral architecture also has a maintenance cost: you own renderer upgrades, font availability, sandboxing, and a compatibility corpus. A hosted conversion service can reduce that operational work, while a self-hosted library can offer tighter data residency and predictable deployment. Neither choice removes the need for page and pixel budgets.
Before shipping, walk through the operational checklist in prose: verify page count before rasterization; calculate a pixel ceiling from the target DPI; render the first visible page under a separate deadline; record per-page metrics; classify deterministic overload separately from transient worker pressure; cap retries; and test the policy against real invoice variants. Then review the rejection message with support, because “preview deferred” is actionable while “conversion timed out” is not.
The PDF specification defines the document format, but it does not define your product’s latency target or thumbnail policy. Those are engineering decisions. Treat them as testable contracts, and a timeout becomes a signal for routing work instead of a mystery to hide behind a larger number.
