YAML-Einrückungsfehler: Warum die CI-Pipeline fehlschlägt

VeröffentlichtToolYAML-Prüfung & -Formatierung

Inhalt
  1. Warum CI-Deployments an der Einrückung scheitern
  2. So finden Sie die fehlerhafte Zeile
  3. Typische Stolperstellen
  4. Fazit
  5. Häufige Fragen

Sie haben nur eine Konfigurationsdatei für GitHub Actions oder GitLab CI leicht angepasst, committet – und schon meldet die Pipeline, dass das Deployment fehlgeschlagen ist. Im Code-Diff ist kein einziges Zeichen eines Befehls geändert, und die tatsächliche Ursache ist oft ein kaum sichtbares Leerzeichen. YAML kennzeichnet Hierarchien nicht mit geschweiften Klammern, sondern über die Anzahl der Einrückungsleerzeichen. Deshalb ist schon ein einzelnes Leerzeichen Teil der Syntax.

Zusammenfassung ① YAML kennzeichnet Hierarchien nicht mit geschweiften Klammern oder Kommas, sondern allein durch Zeilenumbrüche und die Anzahl der Einrückungsleerzeichen ② Einträge auf derselben Ebene müssen exakt gleich weit eingerückt sein. Weicht auch nur einer ab, wird er einer anderen Ebene zugeordnet oder die Struktur ist insgesamt fehlerhaft ③ Auch wenn der Text auf dem Bildschirm sauber ausgerichtet aussieht, lässt sich die tatsächliche Anzahl der Leerzeichen und eine Vermischung mit Tabs nur zuverlässig feststellen, wenn Sie die Datei durch einen Parser laufen lassen

Warum CI-Deployments an der Einrückung scheitern

GitHub Actions, GitLab CI, Kubernetes-Manifeste, docker-compose und die meisten anderen CI/CD-Konfigurationsdateien sind in YAML geschrieben. Anders als JSON markiert YAML Anfang und Ende von Unterelementen nicht mit geschweiften oder eckigen Klammern, sondern nur über die Einrückungstiefe der Zeilen.

Zeilen mit derselben Einrückung gehören zur selben Ebene, und eine tiefer eingerückte Zeile wird zum Unterelement der Zeile direkt darüber. Dadurch wird die Anzahl der Leerzeichen selbst zum Bestandteil der Syntax. Weicht sie auch nur um ein Leerzeichen ab, ergibt sich eine völlig andere Struktur.

Das Problem: Dieser Unterschied ist kaum zu sehen. Im Editor wirken ein paar Leerzeichen mehr oder weniger ähnlich ausgerichtet. Und Zeilen, die Sie aus einem anderen Dokument oder dem Code einer anderen Person einfügen, bringen deren Einrückung mit und passen dadurch leicht nicht zu den umgebenden Zeilen.

Fehlt zum Beispiel bei nur einem Eintrag einer mehrstufigen steps-Liste ein Leerzeichen, wird dieser Eintrag in die falsche Ebene verschoben, oder der Parser kann die Struktur nicht mehr auswerten und bricht mit einem Fehler ab. Im CI-Log steht häufig nur eine kurze Fehlermeldung, sodass sich allein anhand des Logs kaum erkennen lässt, welche Zeile die Ursache ist.

So finden Sie die fehlerhafte Zeile

Wenn Sie im Editor die Anzeige von Leerzeichen (Whitespace bzw. „invisible characters“) aktivieren, werden Leerzeichen und Tabs mit unterschiedlichen Symbolen dargestellt. So erkennen Sie Zeichen, die sich auf dem Bildschirm sonst nicht unterscheiden lassen. Auch die Anzeige der Einrückungslinien („Indent Guides“) hilft, auf einen Blick zu prüfen, ob Zeilen derselben Ebene an einer senkrechten Linie ausgerichtet sind.

Wenn Sie auch so nichts finden, können Sie die Datei ab der ersten Zeile Stück für Stück durchzählen. Sie prüfen dann von Hand, um wie viele Leerzeichen eine untergeordnete Zeile gegenüber ihrer übergeordneten Zeile eingerückt ist, und finden so die Abweichung. Je länger die Datei ist, desto mehr Zeit kostet das, und beim Zählen passieren leicht Fehler.

Mit unserem Tool prüfen. Wenn Sie Ihr YAML einfügen oder die Datei laden, wertet ein eigener Parser die Struktur neu aus und nennt Ihnen direkt die Nummer der Zeile, deren Einrückung nicht stimmt.

YAML-Prüfung & -Formatierung

Kostenlos · ohne Anmeldung · Zeilennummer des YAML-Fehlers direkt im Browser prüfen

Typische Stolperstellen

SituationUrsache
Im Editor sieht alles ausgerichtet aus, trotzdem tritt ein Fehler aufTabs und Leerzeichen sind gemischt. Auf dem Bildschirm wirken sie gleich, der Parser behandelt sie aber als unterschiedliche Einrückung
Nach dem Einfügen eines YAML-Ausschnitts aus einem anderen Dokument tritt ein Fehler aufDie Einrückung des Originals unterscheidet sich von der aktuellen Datei, sodass die Ebenen zu den Zeilen davor und danach nicht passen
Nur ein Eintrag einer Liste (Einträge, die mit - beginnen) ist fehlerhaftWeicht die Einrückung bei gleichrangigen Einträgen auch nur um ein Leerzeichen ab, wird genau dieser Eintrag in eine andere Ebene abgetrennt
Im CI-Log erscheint keine Nummer der fehlerhaften ZeileDas Log meldet nur, dass das Parsen fehlgeschlagen ist. Die verursachende Zeile finden Sie nur, indem Sie die Datei selbst validieren

Alle in der Tabelle genannten Situationen folgen derselben Regel: Die Anzahl der Einrückungsleerzeichen bestimmt die Ebene. Wenn Sie die Datei durch ein Validierungstool laufen lassen, sehen Sie diesen leicht zu übersehenden Unterschied direkt anhand der Zeilennummer.

Fazit

CI/CD-Konfigurationsdateien sind meist in YAML geschrieben, und YAML kennzeichnet Hierarchien nicht mit geschweiften Klammern, sondern über die Anzahl der Einrückungsleerzeichen. Einträge derselben Ebene müssen exakt gleich weit eingerückt sein. Schon ein einziges abweichendes Leerzeichen führt dazu, dass der Eintrag einer anderen Ebene zugeordnet wird oder das Parsen ganz fehlschlägt.

Sie können mit der Whitespace-Anzeige des Editors visuell prüfen oder die Leerzeichen selbst zählen. Je länger die Datei wird, desto schneller und genauer ist es jedoch, sie durch ein Validierungstool laufen zu lassen und die Zeilennummer direkt abzulesen.

YAML-Prüfung & -Formatierung

Kostenlos · ohne Anmeldung · Zeilennummer des YAML-Fehlers direkt im Browser prüfen

Häufige Fragen

Im CI-Log steht keine Zeilennummer des Fehlers: wie finde ich die fehlerhafte Zeile?

Die Logs der CI-Tools selbst melden meist nur, dass das Parsen fehlgeschlagen ist, und nennen oft nicht die genaue Zeilennummer. Wenn Sie die Konfigurationsdatei unverändert in einen separaten YAML-Validator einfügen, zeigt der Parser Ihnen anhand der Zeilennummer, ab welcher Zeile die Zuordnung der Ebenen nicht mehr stimmt.

Zwei oder vier Leerzeichen: Was ist bei der YAML-Einrückung richtig?

Die YAML-Spezifikation schreibt keine bestimmte Anzahl vor. Innerhalb einer Datei müssen Einträge derselben Ebene aber zwingend gleich weit eingerückt sein. Wichtig ist daher, im gesamten Projekt einheitlich entweder zwei oder vier Leerzeichen zu verwenden. In den Beispieldokumenten zu GitHub Actions und GitLab CI werden meist zwei Leerzeichen verwendet.

Darf ich Tabs und Leerzeichen mischen?

Nein. Die YAML-Spezifikation erlaubt für die Einrückung keine Tabulatorzeichen. Da ein Tab je nach Editor unterschiedlich breit dargestellt wird, kann der Parser nicht einheitlich entscheiden, wie vielen Leerzeichen ein Tab als Einrückung entspricht.

Dieser Artikel basiert auf unserem koreanischen Original. Koreanisches Original lesen

Ähnliche Artikel

  1. YouTube automatische Untertitel: Fehler, SRT oder VTT wählenWarum automatisch erzeugte YouTube-Untertitel bei Namen und Fachbegriffen danebenliegen, wie sie sich von manuellen unterscheiden und wann SRT, VTT oder TXT passt.
  2. Zeilennummern hinzufügen: 5 Formate und führende NullenSo nummerieren Sie Zeilen in Text oder Code automatisch, etwa als 1., [1] oder 01., lassen Leerzeilen aus und verstehen, wie die Stellenzahl berechnet wird.
  3. Anagramm prüfen: Anleitung und Algorithmus im ÜberblickAnagramme erkennen in vier Schritten: Zeichen bereinigen, sortieren, vergleichen. Dazu ein schneller Algorithmus mit Hashmap.
  4. Schimpfwortfilter: Text zensieren ohne FehltrefferTeilwort- oder Ganzwort-Treffer, längste Wörter zuerst und das Scunthorpe-Problem: So maskieren Sie Schimpfwörter automatisch, ohne harmlose Wörter zu zensieren.
  5. Base32-Kodierung erklärt: Prinzip, Padding und OTP-SchlüsselSo funktioniert Base32 nach RFC 4648: 5-Bit-Umwandlung, warum 0, 1, 8 und 9 fehlen, Padding mit „=“ berechnen und OTP-Geheimschlüssel für 2FA dekodieren.
  6. Base64 kodieren und dekodieren: Funktionsweise und UmlauteWie Base64 funktioniert: 6-Bit-Umwandlung, 33 % mehr Datenvolumen, Padding mit =, Umlaute und Emojis per UTF-8 und der Unterschied zur Verschlüsselung.

Passende Tools