Exit-Codes

Jeder Befehl endet mit einem von sechs Exit-Codes. Ein Skript oder CI-Schritt kann danach verzweigen, ohne die Ausgabe zu lesen.

Code	Bedeutung	Typische Ursache
0	Erfolg	Auch --help und --version
1	Validierungs- oder Testfehler	Eine Vorlage hat Fehler oder passt nicht zu ihrem Snapshot, eine erzeugte Datei ist veraltet, eine Vorschau ließ sich nicht rendern; siehe die Liste unten. Die Diagnosen werden ausgegeben.
2	Bedienfehler	Unbekannter Befehl oder unbekanntes Flag, ein fehlendes Argument, init in einem Ordner, der schon eine formfeed.json hat, keine formfeed.json bei einem Befehl, der ein Projekt braucht, eine Vorlage oder ein Datensatz, den es nicht gibt, eine formfeed.json oder Benutzerkonfiguration, die kein gültiges JSON ist, ein belegter Port von formfeed dev und API-Antworten im Bereich 4xx, die nicht unter 3 und 5 stehen, etwa 404 template_not_found, 409 conflict (templates push, nachdem jemand eine neuere Version gespeichert hat, partials push) oder ein 422-Vorlagenfehler
3	Authentifizierungsfehler	Kein Schlüssel, ein unbekannter oder widerrufener Schlüssel (401) und jedes 403: ein fehlender Scope, ein Plan ohne die Funktion, test_output_unavailable. Eine Browser-Anmeldung, die abgelehnt wurde oder deren Code abgelaufen ist.
4	Netzwerk- oder Serverfehler	Timeout, Verbindungsfehler, 5xx (503 nach den Wiederholungen), ein Rendering oder eine Umwandlung, die fehlschlug, während die CLI darauf wartete (render, pdf convert), timeout, wenn sie nicht rechtzeitig fertig wurde, eine Bibliotheksdatei, die files pull nicht herunterladen konnte, und jeder Fehler, den die CLI nicht einordnet
5	Kontingent oder Rate-Limit	402 quota_exceeded, 429 rate_limited nach den Wiederholungen

Die CLI ruft die API über das TypeScript-SDK auf; 429 und 503 werden also bis zu dreimal nach dem Retry-After des Servers wiederholt, bevor ein Code feststeht. Eine API-Antwort bekommt ihren Code nach dem Status: 401 und 403 ergeben 3, 402 und 429 ergeben 5, jedes andere 4xx ergibt 2 und alles Übrige 4.

Exit-Code 1 entsteht bei:

• validate, wenn es einen Fehler findet, auch ein fehlendes Partial. Eine Variable, die im Datensatz fehlt, ist eine Warnung und lässt nichts scheitern.
• test, wenn es einen Snapshot-Unterschied findet, einen Datensatz mit Fehlern oder eine Word- oder PowerPoint-Vorlage, die sich nicht füllen lässt. Ein Datensatz ohne genehmigten Snapshot lässt nichts scheitern.
• types --check, wenn die Datei von dem abweicht, was formfeed types schreiben würde.
• ci preview, wenn mindestens ein Rendering fehlschlug oder sich eine Word- oder PowerPoint-Vorlage nicht füllen ließ; die Zusammenfassung nennt sie.
• renders pull --run oder --snapshot, wenn die Vorlage mit den geholten Daten nicht rendert.
• render, wenn sich eine Word- oder PowerPoint-Vorlage nicht füllen lässt (die Funde nennen Teil und Absatz) und wenn eine Vorlage, deren pdf.ua-Prüfung strict ist, die PDF/UA-1-Validierung nicht besteht; die CLI gibt die verletzten Regeln aus.
• einvoice, wenn die E-Rechnungs-Einstellungen der Vorlage ungültig sind oder der _invoice-Block des Datensatzes keine E-Rechnung ergibt.
• templates push, wenn eine Vorlage ein Partial einbindet, zu dem es keine Datei gibt, und bei templates push, channels set, promote und rollback, wenn die Schema-Prüfung eine brechende Änderung findet und --allow-breaking fehlt.
• Einem Vorlagenordner, der template.html und template.docx (oder template.pptx) zugleich enthält, einer template.json, deren kind nicht zur Datei im Ordner passt, einer JSON-Datei im Ordner, die sich nicht lesen lässt, und einer .formfeed/brand.json, die sich nicht lesen lässt.
• import apitemplate, wenn sich keine einzige Vorlage importieren ließ.

Zwei Fälle, die sich ähneln, enden verschieden. Ein Rendering, das die API in ihrer Antwort ablehnt (ein Problem wie 422 template_runtime_error oder 422 page_limit_exceeded), endet in render mit 2 und beendet ci preview mit 2, bevor die Zusammenfassung geschrieben ist; ein Rendering, das fehlschlägt, nachdem es eingereiht wurde, endet in render mit 4 und erscheint in ci preview als fehlgeschlagen, das dann mit 1 endet.

Ausgabe bei einem Fehlschlag

Ohne --json gibt ein Fehlschlag error: <Meldung> auf stderr aus, gefolgt von den Feldfehlern des Problems, wenn die API welche mitgeschickt hat.

Mit --json gibt ein Fehlschlag ein einzelnes JSON-Objekt auf stdout aus, mit ok: false, error (der Meldung), exit_code und details; bei API-Fehlern enthält details das Problem des Servers. Für formfeed render invoice --remote --json, wenn der Workspace keine veröffentlichte Vorlage invoice hat:

{
  "ok": false,
  "error": "No published template \"invoice\" in workspace production",
  "exit_code": 2,
  "details": {
    "type": "https://docs.formfeed.dev/errors/template-not-found",
    "title": "Template not found",
    "status": 404,
    "detail": "No published template \"invoice\" in workspace production",
    "code": "template_not_found",
    "request_id": "req_…"
  }
}

Befehle, die zuerst ihr eigenes Ergebnis ausgeben (validate, test, ci preview, renders pull, import apitemplate), enden mit dem Code ohne ein zweites Objekt; ihr Ergebnis enthält ok: false oder die fehlgeschlagenen Zeilen. Ein unbekannter Befehl oder ein unbekanntes Flag gibt die Bedienungshilfe auf stderr aus, nie ein JSON-Objekt.

formfeed render invoice --json || echo "fehlgeschlagen mit $?"