AEONHOST / WISSEN

YAML-Fehler in Minecraft-Plugin-Konfigurationen finden

Meldet ein Plugin beim Lesen seiner config.yml einen YAML-Fehler, sichere die Datei und prüfe zuerst die genannte Zeile samt den Zeilen davor und danach. Häufige Ursachen sind ein Tab in der Einrückung, unterschiedlich eingerückte Geschwister, eine unvollständige Anführungszeichenfolge oder ein falsch aufgebauter Listenpunkt. Die genaue Fehlermeldung hängt vom Plugin und dessen Parser ab. Verwende die Beispielkonfiguration für genau die Plugin-Version und lösche die Datei nicht pauschal.

Aktualisiert am 07.10.2026

Meldet ein Plugin beim Lesen seiner config.yml einen YAML-Fehler, sichere die Datei und prüfe zuerst die genannte Zeile samt den Zeilen davor und danach. Häufige Ursachen sind ein Tab in der Einrückung, unterschiedlich eingerückte Geschwister, eine unvollständige Anführungszeichenfolge oder ein falsch aufgebauter Listenpunkt. Die genaue Fehlermeldung hängt vom Plugin und dessen Parser ab. Verwende die Beispielkonfiguration für genau die Plugin-Version und lösche die Datei nicht pauschal.

Syntaxfehler und falsche Einstellungen trennen

YAML beschreibt die Struktur einer Datei. Es sagt nicht, welche Schlüssel ein bestimmtes Plugin unterstützt. Eine Datei kann syntaktisch gültig sein und trotzdem einen falschen Schlüssel, Wert oder Datentyp enthalten. Prüfe daher den Plugin-Namen, die installierte Version, den betroffenen Dateipfad und den vollständigen Logeintrag, bevor du Änderungen vornimmst.

Nicht jedes Plugin muss dieselbe YAML-Bibliothek oder dieselbe Fehlerausgabe verwenden. Ein konkretes Beispiel ist Spigots YamlConfiguration: Die API dokumentiert, dass loadFromString bei ungültigem Inhalt eine InvalidConfigurationException wirft. loadConfiguration protokolliert Ladefehler und kann eine leere Konfiguration zurückgeben. Das beschreibt diese API, nicht das Verhalten jedes Plugins. Die Spigot-API-Referenz zeigt beide Fälle.

Die gemeldete Stelle Schritt für Schritt prüfen

  1. Fehlertext festhalten. Kopiere Plugin-Name, Version, Dateiname sowie die vollständige Parsermeldung mit Zeile und Spalte. Notiere auch, ob der Serverstart oder nur das Laden des Plugins betroffen ist. Teile keine vollständige Konfiguration öffentlich; darin können Zugangsdaten oder private Servernamen stehen.
  2. Datei sichern und lesbar öffnen. Lade eine Kopie herunter oder speichere den Originaltext getrennt. Öffne die Konfiguration in einem reinen Texteditor. Wenn möglich, lass Tabs und Leerzeichen sichtbar anzeigen. Vergleiche sie mit der Vorlage, die die Dokumentation für genau diese Plugin-Version nennt.
  3. Einrückung kontrollieren. YAML-Blockstrukturen werden mit Leerzeichen eingerückt; Tabs sind für die Einrückung nicht zulässig. Untergeordnete Werte stehen weiter innen als ihr übergeordneter Schlüssel, gleichrangige Schlüssel auf derselben Stufe. Korrigiere nur den betroffenen Block und übernimm dessen Einrückung konsistent. Die YAML-1.2.2-Spezifikation beschreibt diese Regeln.

Ein strukturell gültiges Beispiel sieht so aus:

messages:
  welcome: "Willkommen!"
worlds:
  - lobby
  - survival

Die Namen messages, welcome und worlds dienen nur zur Darstellung der YAML-Struktur. Übernimm für dein Plugin ausschliesslich dokumentierte Schlüssel. Ein Listenpunkt beginnt mit einem Bindestrich und einem Leerzeichen; alle Einträge derselben Liste müssen untereinander auf derselben Ebene stehen.

  1. Werte, Schlüssel und Anführungszeichen prüfen. Kontrolliere, ob jedes öffnende " oder ' geschlossen wird. In ungequoteten Textwerten können : eine Schlüssel-Wert-Grenze und # einen Kommentar einleiten. Wenn ein Wert solche Zeichen enthalten soll, setze ihn nach der Plugin-Vorlage in Anführungszeichen. In doppelt quotierten Werten müssen enthaltene Anführungszeichen und Backslashes korrekt maskiert sein. Prüfe auch, ob derselbe Schlüssel innerhalb desselben YAML-Mappings doppelt vorkommt: YAML-Mappings verlangen eindeutige Schlüssel. Die Spezifikation hält diese Regel fest. Ob und wie ein Pluginparser ein Duplikat meldet, hängt von Parserbibliothek, Version und Einstellungen ab. Suche deshalb beide Vorkommen und vergleiche sie mit der Konfiguration für genau diese Plugin-Version, auch wenn der Parser keinen Fehler ausgibt.
  2. Vor und nach der genannten Zeile lesen. Die Zeilen- und Spaltenangabe ist ein Startpunkt. Ein fehlendes Anführungszeichen oder ein zu weit eingerückter Listenpunkt kann erst an einer späteren Zeile auffallen. Die Position gehört zur konkreten Parsermeldung: In der verlinkten SnakeYAML-Quellfassung speichert Mark Zeile und Spalte intern ab 0, formatiert die Textausgabe aber ab 1; ein Plugin kann die Meldung zusätzlich umschreiben. Übernimm die Position deshalb so, wie sie im vollständigen Log steht, und prüfe auch die Zeilen davor und danach, statt nur das markierte Zeichen zu ändern.

Änderung auf einer Testkopie prüfen

Bearbeite jeweils nur eine Ursache. Behalte Original und Sicherung, ändere die Datei in einer getrennten Testkopie und folge dem vom Plugin dokumentierten Weg, die Konfiguration neu einzulesen. Ist kein sicherer Reload beschrieben, prüfe die Änderung bei einem normalen Neustart der Testinstanz. Lies danach den neuen Logabschnitt vollständig: Der Parserfehler sollte verschwinden und das Plugin sollte die erwartete Option laden. Kontrolliere diese Option mit der vom Plugin dokumentierten Prüfung; ein erfolgreicher Serverstart allein beweist nicht, dass der Wert übernommen wurde.

Bleibt der Syntaxfehler bestehen, stelle in der Testkopie die gesicherte Datei wieder her und vergleiche den Originalabschnitt erneut mit der versionsgleichen Vorlage. Verschwindet er, aber die Funktion arbeitet anders als beschrieben, prüfst du Schlüsselname, erlaubte Werte und Datentyp des Plugins. Das ist dann eine Plugin-Konfigurationsfrage und nicht automatisch ein YAML-Parserfehler.

Typische Fehlgriffe

  • Die gesamte Datei neu formatieren: Dabei können gültige Bereiche unbeabsichtigt verändert werden. Korrigiere den kleinen betroffenen Block.
  • Eine fremde oder neuere Beispielkonfiguration einsetzen: Schlüssel und Standardwerte können versionsabhängig sein. Bewahre zuerst die vorhandene Datei und prüfe die passende Plugin-Version.
  • Die Datei löschen, damit sie neu erstellt wird: Manche Plugins schreiben Defaults beim Start, andere verhalten sich anders. Verwende einen solchen Weg nur, wenn die Plugin-Dokumentation ihn ausdrücklich beschreibt und die Originaldatei gesichert ist.
  • YAML-Syntax mit Plugin-Bedeutung verwechseln: Eine Liste kann gültiges YAML sein, obwohl das Plugin dort eine Zeichenfolge oder Zuordnung erwartet.

Bei einem Plugin, das nicht lädt, hilft zusätzlich Minecraft-Server-Plugins installieren: Paper und Purpur. Wenn der Fehler den Start verhindert, ordnet Minecraft-Server startet nicht: Logs und Fehler prüfen weitere Startmeldungen ein. Für eine datensparsame Übergabe des relevanten Logausschnitts nutze Gameserver-Logs für eine Supportanfrage vorbereiten.

Quellen