Troubleshooting & Reference · Article 7.4
"The invoice link is broken or the PDF is missing"
PDFs occasionally fail to render (Gotenberg flake) or fail to upload to R2. Symptom: the document shows as "issued" but clicking the link returns 404 or the PDF is blank. Recovery: regenerate from the Documents dropdown.
PDF generation is a multi-step async process: render HTML from a Jinja template, send to Gotenberg (Chrome headless) for PDF conversion, upload bytes to Cloudflare R2, save the URL to the proposal record. Any step can fail in isolation. Clozo's recovery model is "retry from any step" — the Regenerate button rebuilds the missing pieces.
Step by step
Identify the missing PDF.
Open the Documents dropdown on the proposal detail page; the broken document is the one with the 404 link.
Click
Regeneratenext to it.The renderer re-runs; new bytes upload to R2.
Wait ~10 seconds, then retry the link.
New URL replaces the old; the link in any previously-sent email will also resolve to the new file (R2 path is stable).
Why this works this way
The render path is apps/pdf/service.py. Each document type has its own renderer (render_proposal_pdf, render_final_invoice_pdf, render_credit_note_pdf, etc.). On success, the bytes go to apps/storage/r2.py:upload_to_r2() which returns a URL stored on the model.
Failure modes: - Gotenberg timeout (30s default): usually a long template (huge line-item count) or a Gotenberg pod restart. Retry usually succeeds. - R2 upload failure: transient credential or network issue; retry succeeds within minutes. - Phantom invoice: the invoice record was created (number assigned, status set) but the PDF render or upload failed silently. The freelancer sees status "Final invoice issued" but the PDF link 404s.
Race condition specific to amendments: the post-sign hook generates new INV / Storno / Credit Note PDFs in parallel. If one renderer crashes, the others succeed and the model state advances. The missing PDF needs targeted regeneration.
Troubleshooting
Keep reading
Lifecycle
Status: Deposit paid — work can start
The deposit landed (Stripe webhook or manual confirmation). Clozo flips the status, queues the deposit receipt PDF, and starts a behind-the-scenes job to pre-render the final invoice. You can begin the work.
Proposals & Invoices
The 4 delta branches: Δ+, Δ−, Δ=0, Δ_REFUND
Every signed amendment falls into one of four branches based on (a) the sign of the cost change and (b) whether the proposal was already paid. Each branch fires a different document chain. This is the central conceptual map for the entire amendment system.