Skip to main content
Kostenlos starten

Troubleshooting & Reference · Article 7.4

„Der Rechnungslink ist defekt oder das PDF fehlt"

PDFs können gelegentlich nicht gerendert werden (Gotenberg-Fehler) oder der Upload auf R2 schlägt fehl. Symptom: Das Dokument erscheint als „ausgestellt", aber ein Klick auf den Link gibt 404 zurück oder das PDF ist leer. Lösung: Über das Dokumente-Dropdown neu generieren.

Die PDF-Generierung ist ein mehrstufiger asynchroner Prozess: HTML aus einer Jinja-Vorlage rendern, an Gotenberg (Chrome Headless) zur PDF-Konvertierung senden, Bytes auf Cloudflare R2 hochladen, die URL im Angebotsdatensatz speichern. Jeder Schritt kann isoliert fehlschlagen. Clozos Wiederherstellungsmodell lautet „Retry von jedem Schritt" – die Schaltfläche Neu generieren baut die fehlenden Teile neu auf.

Step by step

  1. Fehlendes PDF identifizieren.

    Das Dokumente-Dropdown auf der Angebotsdetailseite öffnen; das defekte Dokument ist das mit dem 404-Link.

  2. Daneben auf Neu generieren klicken.

    Der Renderer wird erneut ausgeführt; neue Bytes werden auf R2 hochgeladen.

  3. Ca. 10 Sekunden warten, dann den Link erneut aufrufen.

    Die neue URL ersetzt die alte; der Link in zuvor versendeten E-Mails wird ebenfalls auf die neue Datei verweisen (R2-Pfad ist stabil).

Why this works this way

Der Render-Pfad ist apps/pdf/service.py. Jeder Dokumenttyp hat seinen eigenen Renderer (render_proposal_pdf, render_final_invoice_pdf, render_credit_note_pdf usw.). Bei Erfolg gehen die Bytes an apps/storage/r2.py:upload_to_r2(), das eine URL zurückgibt, die im Modell gespeichert wird.

Fehlerarten: - Gotenberg-Timeout (Standard 30 s): meist eine lange Vorlage (hohe Anzahl von Positionen) oder ein Gotenberg-Pod-Neustart. Ein erneuter Versuch ist in der Regel erfolgreich. - R2-Upload-Fehler: vorübergehendes Anmeldedaten- oder Netzwerkproblem; Retry gelingt innerhalb von Minuten. - Phantom-Rechnung: Der Rechnungsdatensatz wurde erstellt (Nummer vergeben, Status gesetzt), aber das PDF-Render oder der Upload ist still fehlgeschlagen. Der Freiberufler sieht den Status „Schlussrechnung ausgestellt", aber der PDF-Link gibt 404 zurück.

Racebedingung spezifisch für Nachträge: Der Post-Sign-Hook generiert neue INV-/Storno-/Gutschrift-PDFs parallel. Wenn ein Renderer abstürzt, gelingen die anderen und der Modellstatus schreitet voran. Das fehlende PDF benötigt eine gezielte Neugenerierung.

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.

„Der Rechnungslink ist defekt oder das PDF fehlt" · Help · Clozo