Skip to main content

Fehlerbehebung bei Jekyll-Build-Fehlern für GitHub Pages-Websites

Mithilfe der Jekyll-Build-Fehlermeldungen kannst du Probleme auf deiner GitHub Pages-Website beheben.

GitHub Pages ist in öffentlichen Repositorys mit GitHub Free und GitHub Free für Organisationen sowie in öffentlichen und privaten Repositorys mit GitHub Pro, GitHub Team, GitHub Enterprise Cloud und GitHub Enterprise Server verfügbar. Weitere Informationen findest du unter GitHub-Produkte.

Fehlerbehebung bei Build-Fehlern

Wenn beim Erstellen deiner GitHub Pages-Website (lokal oder auf GitHub) mit Jekyll ein Fehler auftritt, kannst du die Fehlerbehebung mithilfe der Fehlermeldungen durchführen. Weitere Informationen zu Fehlermeldungen und deren Anzeige findest du unter Informationen zu Jekyll-Buildfehlern für GitHub Pages-Websites.

Wenn du eine generische Fehlermeldung erhalten hast, suche nach häufigen Fehlern.

  • Du verwendest nicht unterstützte Plug-Ins. Weitere Informationen findest du unter Informationen zu GitHub Pages und Jekyll.
  • Dein Repository hat die Größenbeschränkung für Repositorys überschritten. Weitere Informationen findest du unter Welches Datenträgerkontingent gilt für mich?.
  • Du hast die source-Einstellung in deiner Datei _config.yml geändert. Wenn du deine Website über einen Branch veröffentlichst, überschreibt GitHub Pages diese Einstellung während des Buildvorgangs.
  • Ein Dateiname in deinen veröffentlichten Dateien enthält einen Doppelpunkt (:). Dies wird nicht unterstützt.

Wenn du eine bestimmte Fehlermeldung erhalten hast, lies die nachfolgenden Informationen zur Fehlerbehebung für die jeweilige Fehlermeldung.

Nachdem du Fehler behoben hast, löse einen anderen Build aus, indem du die Änderungen an den Quellbranch deiner Website pushst (wenn die Veröffentlichung über einen Branch erfolgt) oder deinen benutzerdefinierten GitHub Actions-Workflow auslöst (wenn du die Veröffentlichung mit GitHub Actions vornimmst).

Fehler bei der Dateikonfiguration

Dieser Fehler bedeutet, dass deine Website nicht erstellt werden konnte, weil die Datei _config.yml Syntaxfehler enthält.

Stelle zur Problembehandlung sicher, dass deine _config.yml-Datei folgenden Regeln folgt:

  • Verwende Leerzeichen statt Tabs.
  • Füge nach dem : für jedes Schlüssel-Wert-Paar ein Leerzeichen ein. Beispiel: timezone: Africa/Nairobi.
  • Verwende nur UTF-8-Zeichen.
  • Setze Sonderzeichen wie : in Anführungszeichen. Beispiel: title: "my awesome site: an adventure in parse errors".
  • Verwende | in mehrzeiligen Werten, um neue Zeilen zu erstellen, und >, um neue Zeilen zu ignorieren.

Um eventuelle Fehler zu erkennen, kannst du den Inhalt deiner YAML-Datei in einen YAML-Linter wie YAML Validator kopieren und einfügen.

Datum besitzt ungültiges Datum/Uhrzeit

Dieser Fehler bedeutet, dass eine Seite der Website einen ungültigen Wert für Datum/Uhrzeit enthält.

Zur Fehlerbehebung prüfe die in der Fehlermeldung genannte Datei und deren Layouts auf Aufrufe datumsbezogener Liquid-Filter. Prüfe, ob alle Variablen, die an datumsabhängige Liquid-Filter übergeben werden, Werte enthalten und nicht nil oder "" übergeben. Weitere Informationen findest du in der Liquid-Dokumentation unter Liquid-Filter.

Datei ist im Verzeichnis „includes“ nicht vorhanden

Dieser Fehler bedeutet, dass dein Code auf eine Datei verweist, die sich nicht im Verzeichnis _includes befindet.

Zur Problembehandlung durchsuche die in der Fehlermeldung genannte Datei nach include, um festzustellen, ob du auf andere Dateien verwiesen hast, z. B. {% include example_header.html %}. Wenn sich eine der Dateien, auf die du verwiesen hast, nicht im Verzeichnis _includes befindet, kopiere oder verschiebe die Dateien in das Verzeichnis _includes.

Dieser Fehler bedeutet, dass der Code auf eine per Symlink verknüpfte Datei verweist, die sich nicht in den veröffentlichten Dateien für deine Website befindet.

Zur Problembehandlung durchsuche die in der Fehlermeldung genannte Datei nach include, um festzustellen, ob du auf andere Dateien verwiesen hast, z. B. {% include example_header.html %}. Wenn eine der Dateien, auf die du verwiesen hast, per Symlink verknüpft ist, kopiere oder verschiebe die Datei in das Verzeichnis _includes.

Datei ist nicht ordnungsgemäß UTF-8-codiert

Dieser Fehler bedeutet, dass du nicht lateinische Buchstaben wie 日本語 verwendet hast, ohne dem Computer mitzuteilen, dass er diese Symbole erwarten soll.

Zur Problembehandlung erzwingst du die UTF-8-Kodierung, indem du die folgende Zeile deiner _config.yml-Datei hinzufügst:

encoding: UTF-8

Textmarkersprache ungültig

Dieser Fehler bedeutet, dass du andere Syntaxmarker als Rouge oder Pygments in deiner Konfigurationsdatei angegeben hast.

Zur Problembehandlung aktualisierst du deine _config.yml-Datei, um Rouge oder Pygments anzugeben. Weitere Informationen findest du unter Informationen zu GitHub und Jekyll.

Ungültiges Beitragsdatum

Dieser Fehler bedeutet, dass ein Beitrag auf deiner Website ein ungültiges Datum im Dateinamen oder im YAML-Frontmatter enthält.

Zur Fehlerbehebung formatiere alle Datumsangaben als YYYY-MM-DD HH:MM:SS für UTC, und prüfe, ob gültige Kalenderdaten angegeben sind. Um eine Zeitzone mit einer Abweichung von UTC festzulegen, verwende das Format JJJJ-MM-TT hh:mm:ss +/- tttt, z. B. 2014-04-18 11:30:00 +0800.

Wenn du ein Datumsformat in deiner Datei _config.yml angibst, stelle sicher, dass das Format richtig ist.

Sass oder SCSS ungültig

Dieser Fehler bedeutet, dass dein Repository eine Sass- oder SCSS-Datei mit ungültigem Inhalt enthält.

Zur Fehlerbehebung prüfe die in der Fehlermeldung genannte Zeilennummer auf ungültige Sass oder SCSS. Damit solche Fehler in Zukunft vermieden werden, installiere einen Sass- oder SCSS-Linter für deinen meistgenutzten Text-Editor.

Ungültiges Submodul

Dieser Fehler bedeutet, dass dein Repository ein nicht ordnungsgemäß initialisiertes Submodul enthält.

Zur Fehlerbehebung entscheide zuerst, ob du tatsächlich ein Submodul verwenden möchtest, bei dem es sich um ein Git-Projekt innerhalb eines Git-Projekts handelt; Submodule werden manchmal versehentlich erstellt.

Wenn du kein Submodul verwenden möchtest, entferne das Submodul, und ersetze dabei PFAD-ZUM-SUBMODUL durch den Pfad zum Submodul:

$ git submodule deinit PATH-TO-SUBMODULE
$ git rm PATH-TO-SUBMODULE
$ git commit -m "Remove submodule"
$ rm -rf .git/modules/PATH-TO-SUBMODULE

Wenn du das Untermodul verwenden möchtest, stelle sicher, dass du beim Verweisen auf das Untermodul https:// (nicht http://) verwendest, und dass sich das Untermodul in einem öffentlichen Repository befindet.

Ungültige YAML in der Datendatei

Dieser Fehler bedeutet, dass eine der weiteren Dateien im _data-Ordner ungültige YAML enthält.

Stelle zur Problembehandlung sicher, dass die YAML-Dateien in deinem _data-Ordner folgende Regeln erfüllen:

  • Verwende Leerzeichen statt Tabs.
  • Füge nach dem : für jedes Schlüssel-Wert-Paar ein Leerzeichen ein. Beispiel: timezone: Africa/Nairobi.
  • Verwende nur UTF-8-Zeichen.
  • Setze Sonderzeichen wie : in Anführungszeichen. Beispiel: title: "my awesome site: an adventure in parse errors".
  • Verwende | in mehrzeiligen Werten, um neue Zeilen zu erstellen, und >, um neue Zeilen zu ignorieren.

Um eventuelle Fehler zu erkennen, kannst du den Inhalt deiner YAML-Datei in einen YAML-Linter wie YAML Validator kopieren und einfügen.

Weitere Informationen zu Jekyll-Datendateien findest du in der Jekyll-Dokumentation unter Datendateien.

Markdown-Fehler

Dieser Fehler bedeutet, dass dein Repository Markdownfehler enthält.

Zur Fehlerbehebung verwende einen unterstützten Markdown-Prozessor. Weitere Informationen findest du unter Festlegen eines Markdown-Prozessors für deine GitHub Pages-Website mithilfe von Jekyll.

Prüfe außerdem, ob die in der Fehlermeldung genannte Datei eine gültige Markdown-Syntax umfasst. Weitere Informationen findest du unter Markdown: Syntax auf Daring Fireball.

Dokumentordner fehlt

Dieser Fehler bedeutet, dass du den docs-Ordner in einem Branch als Veröffentlichungsquelle ausgewählt hast, aber es gibt in diesem Branch keinen docs-Ordner im Stamm deines Repositorys.

Wenn dein docs-Ordner versehentlich verschoben wurde, versuche zur Problembehandlung, den docs-Ordner zurück in den Stamm deines Repositorys auf dem Branch zu verschieben, den du für deine Veröffentlichungsquelle gewählt hast. Wenn der docs-Ordner versehentlich gelöscht wurde, kannst du entweder:

  • Mache den Löschvorgang mit Git rückgängig. Weitere Informationen findest du in der Git-Dokumentation unter git-revert.
  • Erstelle einen neuen docs-Ordner im Stamm deines Repositorys auf dem Branch, den du für die Veröffentlichungsquelle ausgewählt hast, und füge die Quelldateien deiner Website dem Ordner hinzu. Weitere Informationen findest du unter Erstellen neuer Dateien.
  • Ändere die Veröffentlichungsquelle. Weitere Informationen findest du unter Konfigurieren einer Veröffentlichungsquelle für GitHub Pages.

Submodul fehlt

Dieser Fehler bedeutet, dass dein Repository ein nicht vorhandenes oder ein nicht ordnungsgemäß initialisiertes Submodul enthält.

Zur Fehlerbehebung entscheide zuerst, ob du tatsächlich ein Submodul verwenden möchtest, bei dem es sich um ein Git-Projekt innerhalb eines Git-Projekts handelt; Submodule werden manchmal versehentlich erstellt.

Wenn du kein Submodul verwenden möchtest, entferne das Submodul, und ersetze dabei PFAD-ZUM-SUBMODUL durch den Pfad zum Submodul:

$ git submodule deinit PATH-TO-SUBMODULE
$ git rm PATH-TO-SUBMODULE
$ git commit -m "Remove submodule"
$ rm -rf .git/modules/PATH-TO-SUBMODULE

Soll ein Submodul verwendet werden, initialisiere das Submodul. Weitere Informationen findest du unter Git-Tools – Untermodule im Pro Git-Buch.

Dieser Fehler bedeutet, dass du relative Permalinks in der Datei _config.yml nutzt, die nicht von GitHub Pages unterstützt werden.

Permalinks sind permanente URLs, die auf einen bestimmten Beitrag oder eine bestimmte Seite deiner Website verweisen. Absolute Permalinks beginnen mit dem Root der Website, relative Permalinks dagegen mit dem Ordner, in dem sich die referenzierte Seite befindet. GitHub Pages und Jekyll unterstützen relative Permalinks nicht mehr. Weitere Informationen zu Permalinks findest du in der Jekyll-Dokumentation unter Permalinks.

Entferne zur Problembehandlung die relative_permalinks-Zeile aus der Datei _config.yml, und formatiere alle relativen Permalinks auf deiner Website in absolute Permalinks um. Weitere Informationen findest du unter Bearbeiten von Dateien.

Dieser Fehler bedeutet, dass die Website einen symbolischen Link (Symlink) enthält, der sich nicht in den veröffentlichten Dateien für die Website befindet. Weitere Informationen zu Symlinks findest du unter Symbolische Verknüpfung in Wikipedia.

Zur Fehlerbehebung prüfe, ob die in der Fehlermeldung genannte Datei für den Build der Website erforderlich ist. Falls nicht (oder falls die Datei kein Symlink sein soll), lösche die Datei. Wenn die Datei, auf die der Symlink verweist, für den Build der Website erforderlich ist, stelle sicher, dass die Datei oder das Verzeichnis, auf die bzw. das der Symlink verweist, in den veröffentlichten Dateien für deine Website vorhanden ist. Um externe Ressourcen einzubinden, solltest du git submodule oder einen Paketmanager eines Drittanbieters wie Bower verwenden. Weitere Informationen findest du unter Verwendung von Submodulen mit GitHub Pages.

Syntaxfehler in der „for“-Schleife

Dieser Fehler bedeutet, dass dein Code ungültige Syntax in einer Liquid-for-Schleifen-Deklaration enthält.

Vergewissere dich zur Problembehandlung, dass alle for-Schleifen in der in der Fehlermeldung erwähnten der Datei die richtige Syntax haben. Weitere Informationen zur richtigen Syntax für for-Schleifen findest du in der Liquid-Dokumentation unter Iterations-Tags.

Tag nicht ordnungsgemäß geschlossen

Diese Fehlermeldung bedeutet, dass dein Code ein logisches Tag enthält, das nicht korrekt geschlossen ist. {% capture example_variable %} muss z. B. von {% endcapture %} geschlossen werden.

Zur Fehlerbehebung prüfe, ob alle logischen Tags in der Datei, die in der Fehlermeldung genannt ist, ordnungsgemäß geschlossen sind. Weitere Informationen findest du in der Liquid-Dokumentation unter Liquid-Tags.

Tag nicht ordnungsgemäß beendet

Diese Fehlermeldung bedeutet, dass dein Code ein output-Tag enthält, das nicht korrekt beendet wurde. Beispiel: {{ page.title } anstelle von {{ page.title }}.

Vergewissere dich zur Problembehandlung, dass alle Ausgabe-Tags in der in der Fehlermeldung erwähnten Datei mit }} beendet werden. Weitere Informationen findest du in der Liquid-Dokumentation unter Liquid-Objekte.

Unbekannter Tag-Fehler

Dieser Fehler bedeutet, dass dein Code ein nicht erkanntes Liquid-Tag enthält.

Zur Fehlerbehebung prüfe, ob alle Liquid-Tags in der Datei, die in der Fehlermeldung genannt ist, den Jekyll-Standardvariablen entsprechen und ob die Tag-Namen korrekt geschrieben sind. Eine Liste der Standardvariablen findest du in der Jekyll-Dokumentation unter Variablen.

Nicht unterstützte Plug-ins sind häufig die Quelle für unbekannte Tags. Wenn du ein nicht unterstütztes Plug-in auf der Website verwendest, also die Website lokal erstellen und die statischen Dateien per Push-Verfahren an GitHub übertragen, darf das Plug-in keine Tags umfassen, die nicht in den Jekyll-Standardvariablen aufgeführt sind. Eine Liste der unterstützten Plugins findest du unter Informationen zu GitHub Pages und Jekyll.