Formatierer

Häufige YAML-Fehler: Einrückung, Tabs und „mapping values are not allowed here“

Zuletzt aktualisiert am

Die meisten YAML-Fehler haben drei Ursachen: Tabs statt Leerzeichen, eine Einrückung, die nicht zur Struktur passt, oder ein Sonderzeichen in einem Wert, der nicht in Anführungszeichen steht. Die Meldung des Parsers zeigt meist nur, wo er nicht mehr weiterkam. Der eigentliche Fehler liegt oft eine Zeile darüber.

Um zu sehen, was dein YAML wirklich bedeutet, öffne es im YAML-Formatierer: Er rückt einheitlich neu ein und behält Kommentare. Mit YAML zu JSON siehst du die Struktur, die der Parser daraus macht. So fallen verrutschte Einrückungen und unerwartete Typen sofort auf. Beides läuft lokal in deinem Browser, es wird nichts an einen Server gesendet.

Zur Schreibweise der Meldungen: Sie unterscheiden sich je nach Bibliothek und Version. Die Beispiele unten stammen von PyYAML (Python, ohne libyaml-Beschleunigung). In js-yaml (JavaScript) und in der Bibliothek yaml von Eemeli Aro lauten dieselben Fehler oft anders. Achte deshalb auf die Zeilen- und Spaltenangabe, nicht auf den exakten Wortlaut.

Tabs statt Leerzeichen

server:
	host: localhost

Vor host steht ein Tab statt Leerzeichen. YAML erlaubt Tabs nicht zum Einrücken, nur Leerzeichen. PyYAML meldet:

while scanning for the next token
found character '\t' that cannot start any token

Lösung: Tab durch Leerzeichen ersetzen, üblich sind zwei.

server:
  host: localhost

Stelle deinen Editor so ein, dass die Tab-Taste Leerzeichen einfügt, und lass dir Whitespace-Zeichen anzeigen. Der YAML-Formatierer rückt mit Leerzeichen ein, falls du eine Datei ohnehin neu formatieren willst.

Uneinheitliche Einrückung

Die Einrückung ist in YAML Syntax: Sie bestimmt, was zu welchem Eintrag gehört. Alle Einträge einer Ebene brauchen dieselbe Zahl von Leerzeichen.

server:
  host: localhost
 port: 8080

port steht eine Spalte weiter links als host, aber weiter rechts als server. Das passt zu keiner Ebene. Ruby (Psych) und PyYAML mit libyaml melden dazu did not find expected key, PyYAML ohne libyaml expected <block end>, but found '<block mapping start>'. Gemeint ist dasselbe: Hier hätte ein weiterer Schlüssel der aktuellen Ebene stehen müssen.

server:
  host: localhost
  port: 8080

Bei Listen gilt das auch für Einträge mit mehreren Schlüsseln:

- name: web
 port: 80

Fix: Der zweite Schlüssel muss genau unter name stehen, also zwei Leerzeichen nach dem Bindestrich.

- name: web
  port: 80

Manchmal ist die Einrückung „zu weit“ und YAML liest die Zeile als Fortsetzung des vorherigen Werts. Das führt direkt zum nächsten Fehler.

„mapping values are not allowed here“

titel: Achtung: Wartung

Der zweite Doppelpunkt mit Leerzeichen dahinter beginnt für YAML einen weiteren Schlüssel, aber an dieser Stelle steht schon ein Wert. PyYAML meldet:

mapping values are not allowed here

Es gibt zwei typische Auslöser. Der erste ist ein Doppelpunkt mit Leerzeichen im Wert wie oben. Lösung: Wert in Anführungszeichen setzen.

titel: "Achtung: Wartung"

Der zweite ist eine zu weit eingerückte Zeile:

name: web
  port: 80

Hier liest der Parser port: 80 als Fortsetzung von web. Die Zeile muss wieder auf die Höhe von name.

name: web
port: 80

Ein Doppelpunkt ohne folgendes Leerzeichen ist dagegen unkritisch: url: http://example.com funktioniert, weil :// kein Schlüssel-Trenner ist.

Fehlendes Leerzeichen nach Doppelpunkt oder Bindestrich

Dieser Fehler ist tückisch, weil oft gar keine Meldung kommt:

person:
  name:Ada
tags:
  -rot
  -blau

Ohne Leerzeichen ist name:Ada kein Schlüssel-Wert-Paar, sondern ein einziger Text. Ebenso sind -rot und -blau keine Listeneinträge: Beide Zeilen werden zum Text "-rot -blau". PyYAML liest dieses Dokument ohne Fehler als {'person': 'name:Ada', 'tags': '-rot -blau'}, also nicht mit der Struktur, die du wolltest. Richtig:

person:
  name: Ada
tags:
  - rot
  - blau

Nach : und - gehört immer ein Leerzeichen. Prüfe im YAML-zu-JSON-Werkzeug, ob du Objekte und Listen bekommst, die du erwartest.

Doppelte Schlüssel

port: 8080
host: localhost
port: 9090

Laut YAML-Spezifikation müssen Schlüssel in einem Objekt eindeutig sein. Ob ein Parser das durchsetzt, ist aber nicht einheitlich: PyYAML übernimmt stillschweigend den letzten Wert (port wird 9090), js-yaml und die Bibliothek yaml von Eemeli Aro melden einen Fehler. Dieselbe Datei kann also in zwei Programmen unterschiedlich laufen.

Doppelte Schlüssel entstehen meist beim Zusammenkopieren von Konfigurationen. Lösung: einen der beiden Einträge entfernen oder umbenennen. Wenn du Einstellungen gezielt überschreiben willst, nutze Anker und Merge-Keys. Das Werkzeug YAML zu JSON löst sie auf, sodass du das Endergebnis siehst.

Sonderzeichen und Wörter, die kein Text sind

Ein Wert ohne Anführungszeichen wird nach festen Regeln gedeutet. Manche Zeichen und Wörter haben dabei eine Sonderbedeutung.

yes, no, on, off. In YAML 1.1 sind das Wahrheitswerte. PyYAML (YAML 1.1) liest yes als true, no als false, on und off ebenso. In YAML 1.2 sind nur true und false Wahrheitswerte. Wenn du den Text meinst, setze Anführungszeichen:

# kann als Wahrheitswert gelesen werden
land: no
# eindeutig ein Text
land: "no"

Das berühmteste Beispiel ist das Länderkürzel NO für Norwegen. Mehr dazu im Ratgeber Das Norwegen-Problem in YAML.

# beginnt einen Kommentar. Ein #, vor dem ein Leerzeichen steht, ist der Anfang eines Kommentars. Alles danach ist weg:

passwort: abc #123

Das Ergebnis ist abc. Mit Anführungszeichen bleibt der Text vollständig: passwort: "abc #123". Ein # mitten im Wort ohne Leerzeichen davor (abc#123) bleibt dagegen erhalten.

@ und Backtick am Anfang. Diese beiden Zeichen sind in YAML reserviert und dürfen einen unquotierten Wert nicht beginnen. PyYAML meldet dazu found character '@' that cannot start any token bzw. dasselbe mit '`'. Auch hier hilft ein Anführungszeichen:

mail: @ada      # falsch
mail: "@ada"    # richtig

*, &, !, %, |, > am Anfang. Auch sie haben eine Bedeutung (Alias, Anker, Tag, Direktive, Block-Text). *x ohne passenden Anker führt zum Fehler found undefined alias. Auch hier gilt: im Zweifel in Anführungszeichen setzen.

Doppelpunkt mit Leerzeichen. Siehe oben, „mapping values are not allowed here“.

Faustregel: Alles, was nicht eindeutig einfacher Text ist, setzt du in doppelte Anführungszeichen. In doppelten Anführungszeichen sind Escape-Sequenzen wie \n möglich, in einfachen nicht. Für mehrzeilige Texte gibt es eigene Schreibweisen, die der Ratgeber Mehrzeilige Strings in YAML erklärt.

So gehst du bei einem YAML-Fehler vor

  1. Zeile und Spalte der Meldung ansehen und die Zeile darüber mitprüfen.
  2. Nach Tabs suchen und durch Leerzeichen ersetzen.
  3. Einrückung prüfen: Gleiche Ebene, gleiche Spalte.
  4. Werte mit :, #, @, Backtick oder Wörtern wie yes/no in Anführungszeichen setzen.
  5. Das Ergebnis mit YAML zu JSON kontrollieren: Stimmt die Struktur, stimmen die Typen?

Wenn du dein YAML danach einheitlich eingerückt haben möchtest, nutze den YAML-Formatierer.

Kurz gesagt

  • YAML verbietet Tabs zum Einrücken. Nutze Leerzeichen, meist zwei pro Ebene.
  • Einrückung ist Struktur: gleiche Ebene, gleiche Spalte. Die gemeldete Zeile ist oft nur die Folge eines Fehlers weiter oben.
  • „mapping values are not allowed here“ bedeutet meist einen Doppelpunkt mit Leerzeichen im unquotierten Wert oder eine zu weit eingerückte Zeile.
  • Nach : und - gehört ein Leerzeichen, sonst entsteht still ein Text statt einer Struktur.
  • Setze Werte mit :, #, @, Backtick oder yes/no in Anführungszeichen. Doppelte Schlüssel behandeln Parser unterschiedlich, also vermeide sie.

Einzelne Meldungen im Detail: „found character that cannot start any token“ und „could not find expected ':'“. Weiterlesen: Was ist YAML?, Das Norwegen-Problem in YAML, JSON vs. YAML. Werkzeuge: YAML-Formatierer, YAML zu JSON.