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

Inhalt
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.
Kostenlos · ohne Anmeldung · Zeilennummer des YAML-Fehlers direkt im Browser prüfen

Typische Stolperstellen
| Situation | Ursache |
|---|---|
| Im Editor sieht alles ausgerichtet aus, trotzdem tritt ein Fehler auf | Tabs 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 auf | Die 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 fehlerhaft | Weicht 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 Zeile | Das 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.
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