PDF generation failures

PDF rendering uses WeasyPrint server-side. Most failures fall into a small set of categories — this article covers them.

Common error messages

"PDF generation failed (500)"

The server raised an unhandled exception while rendering. Causes:

1. Missing template content — your tenant's PDF template has been corrupted or a referenced block doesn't exist. Open Settings → PDF Designer for the relevant doc type and confirm the layout looks right. Re-publishing it usually fixes corruption.
2. Bad logo URL — your tenant's logo_url points to a 404 or a server WeasyPrint can't reach. Re-upload from Settings → Tenant → Branding.
3. Bad font reference — rare; only happens when a custom font CSS rule references a missing file.

"PDF generation timed out"

Document took longer than the server limit (~10 s). Causes:

1. Very large invoice — 200+ line items with embedded images. Split it.
2. Slow image fetch — your logo or screenshot URL is on a slow CDN. Move assets to a faster host or upload directly to /api/uploads/.

"Cannot read properties of undefined (reading '...')"

A JS error from the frontend, not the PDF renderer. Means the data you tried to render is missing a field the template expects. Common cases:

1. Quotation without a customer — backend allows it; PDF doesn't. Fill in a customer.
2. Invoice without a due date — set one before generating.
3. Booking with no charges — add at least one charge line.

Step-by-step diagnosis

1. 1
   Read the exact error message — most messages are diagnostic.
2. 2
   Check whether other documents render fine (e.g. can you open another invoice's PDF?). If yes, the issue is data-specific to this one record.
3. 3
   Check whether the same doc type fails for every tenant user (could be a template issue) or just this user (could be a permission issue).
4. 4
   Try the Designer preview — Settings → PDF Designer → pick the doc type. The preview renders the template with sample data. If the preview works but a real document doesn't, the issue is record-specific.
5. 5
   For a "missing field" error, open the record's edit form and look for required fields that are blank.

Common pitfalls

Regulatory documents (MAWB / HAWB / MBL / HBL / Consol Manifest / CMR)

These render via the regulated-forms pipeline, not the block engine. They're not user-editable. If they fail:

• Confirm the underlying booking has the required fields (vessel name, port codes, container numbers).
• Re-trigger by clicking Print again — most regulated-form failures are transient.
• If persistent, contact support — these renderers don't have a "fall back to defaults" path.

When to contact support

• A document that worked yesterday fails today, and no template change happened.
• The same error message appears across multiple unrelated documents.
• WeasyPrint OOM (out-of-memory) errors — these are platform-side issues we need to scale.

Email [email protected] with the document type, record ID, and exact error.