GitHub Pages サイトの Jekyll ビルドエラーに関するトラブルシューティング

Jekyll ビルドエラーのメッセージを利用して、GitHub Pages サイトの問題をトラブルシューティングすることができます。

この機能を使用できるユーザーについて

GitHub Pagesは、パブリック・リポジトリのGitHub Freeと組織用のGitHub Free、パブリック・リポジトリとプライベート・リポジトリのGitHub Pro、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Serverで利用できます。詳しくは、「GitHub のプラン」をご覧ください。

GitHub Pages で、Jekyll ビルドの実行に GitHub Actions が使用されるようになりました。ビルドのソースとしてブランチを使用する際、組み込みの Jekyll ワークフローを使用する場合は、リポジトリで GitHub Actions を有効にする必要があります。 GitHub Actions が使用できない場合、または無効になっている場合は、ソースブランチのルートに .nojekyll ファイルを追加すると、Jekyll ビルドプロセスがバイパスされ、コンテンツが直接デプロイされます。 GitHub Actions の有効化の詳細については、「リポジトリの GitHub Actions の設定を管理する」を参照してください。

この記事の内容

ビルドエラーのトラブルシューティング

GitHub Pages サイトをローカルで、または GitHub 上でビルドしているときに Jekyll でエラーが発生した場合、そのエラーメッセージをトラブルシューティングに利用できます。エラーメッセージとその表示方法について詳しくは、「GitHub PagesサイトのJekyllビルドエラーについて」をご覧ください。

一般的なエラーメッセージが表示された場合は、よくある問題をチェックします。

サポートされていないプラグインを使用している。詳細については、「GitHub PagesとJekyllについて」を参照してください。
リポジトリがリポジトリサイズの制限を超えている。詳しくは、「GitHub での大きいファイルについて」をご覧ください。
_config.yml ファイルの source 設定を変更しました。ブランチからサイトを公開している場合、この設定はビルドプロセス中に GitHub Pages によってオーバーライドされます。
公開元のファイル名にコロン (:) が含まれていますが、これはサポートされていません。

具体的なエラーメッセージが表示された場合は、エラーメッセージに関する以下のトラブルシューティング情報を確認してください。

エラーを修正したら、サイトのソースブランチに変更をプッシュするか (ブランチから公開している場合)、またはカスタム GitHub Actions ワークフローをトリガーして (GitHub Actions で公開している場合)、別のビルドをトリガーします。

Config file error

このエラーは、_config.yml ファイルに構文エラーが含まれているため、サイトのビルドに失敗したことを意味します。

トラブルシューティングを行うには、_config.yml ファイルが次のルールに従っていることを確認します。

タブの代わりにスペースを使ってください。
timezone: Africa/Nairobi のように、キーと値の各ペアの : の後にスペースを含めます。
UTF-8キャラクタだけを使ってください。
: などの特殊文字は引用符で囲み、title: "my awesome site: an adventure in parse errors" のようにします。
複数行の値の場合は、| を使用して改行を作成し、> を使用して改行を無視します。

エラーを特定するには、YAML ファイルの内容をコピーし、YAML Validator などの YAML リンターに貼り付けます。

Note

If your repository contains symbolic links, you will need to publish your site using a GitHub Actions workflow. For more information about GitHub Actions, see "GitHub Actions ドキュメント."

Date is not a valid datetime

このエラーは、サイトのいずれかのページに無効な日付データが含まれていることを意味します。

トラブルシューティングするには、エラーメッセージで示されたファイルおよびファイルのレイアウトで、日付関連の Liquid フィルタをコールしている箇所を探します。日付関連の Liquid フィルターに渡される変数には、すべてのケースで値が含まれていることを確認し、nil や "" を渡さないようにしてください。詳細については、Liquid ドキュメントの「Liquid filters」(Liquid フィルター) を参照してください。

File does not exist in includes directory

このエラーは、_includes ディレクトリに存在しないファイルをコードが参照していることを意味します。

トラブルシューティングを行うには、エラーメッセージで include のファイルを検索して、{% include example_header.html %} などの他のファイルを参照した場所を確認します。参照したファイルのいずれかが _includes ディレクトリにない場合は、ファイルを _includes ディレクトリにコピーするか、移動します。

File is not properly UTF-8 encoded

このエラーは、これらの記号を期待するようコンピューターに伝えずに、日本語などのラテン文字以外の文字を使用したことを意味します。

トラブルシューティングを行うには、_config.yml ファイルに次の行を追加して UTF-8 エンコードを強制します。

encoding: UTF-8

Invalid highlighter language

このエラーは、構成ファイルで Rouge または Pygments 以外の構文ハイライターを指定したことを意味します。

トラブルシューティングを行うには、_config.yml ファイルを更新して、Rouge または Pygments を指定します。詳しくは、「GitHub PagesとJekyllについて」を参照してください。

Invalid post date

このエラーメッセージは、サイトでの投稿で、ファイル名または YAML フロントマターに無効な日付が含まれていることを意味します。

トラブルシューティングするには、日付がすべて YYYY-MM-DD HH:MM:SS 形式の UTC 時間で、実際のカレンダー日付であることを確認します。 UTC からのオフセットがあるタイムゾーンを指定するには、2014-04-18 11:30:00 +0800 のような YYYY-MM-DD HH:MM:SS +/-TTTT 形式を使用します。

_config.yml ファイルで日付形式を指定する場合は、形式が正しいことを確認してください。

Invalid Sass or SCSS

このエラーは、リポジトリに無効な内容の Sass または SCSS ファイルが含まれていることを意味します。

トラブルシューティングするには、エラーメッセージに含まれている行番号を確認して、無効な Sass または SCSS を探します。今後のエラーを防ぐために、お好みのテキストエディター用の Sass または SCSS 文法チェッカーをインストールします。

Invalid submodule

このエラーは、適切に初期化されていないサブモジュールがリポジトリに含まれていることを意味します。

トラブルシューティングするために、まずGitプロジェクト内のGitプロジェクトであるサブモジュールを本当に使いたいかを判断してください。サブモジュールは偶然作られてしまうことがあります。

サブモジュールを使用しない場合は、サブモジュールを削除し、PATH-TO-SUBMODULE をサブモジュールへのパスに置き換えます。

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

サブモジュールを使用する場合は、サブモジュールを参照するときに https:// を使用し (http:// ではなく)、サブモジュールがパブリックリポジトリにあることを確認してください。

Invalid YAML in data file

このエラーは、_data フォルダー内のいずれかのファイルに無効な YAML が含まれていることを意味します。

トラブルシューティングを行うには、_data フォルダー内の YAML ファイルが次のルールに従っていることを確認します。

タブの代わりにスペースを使ってください。
timezone: Africa/Nairobi のように、キーと値の各ペアの : の後にスペースを含めます。
UTF-8キャラクタだけを使ってください。
: などの特殊文字は引用符で囲み、title: "my awesome site: an adventure in parse errors" のようにします。
複数行の値の場合は、| を使用して改行を作成し、> を使用して改行を無視します。

エラーを特定するには、YAML ファイルの内容をコピーし、YAML Validator などの YAML リンターに貼り付けます。

Jekyll データファイルの詳細については、Jekyll ドキュメントの「Data Files」(データファイル) を参照してください。

Markdown errors

このエラーは、リポジトリ Markdown エラーがあることを意味します。

トラブルシューティングするには、必ずサポートされている Markdown プロセッサを使用するようにします。詳しくは、「Jekyll を使用して、GitHub Pages サイトの Markdown プロセッサを設定する」を参照してください。

次に、エラーメッセージで示されているファイルが有効な Markdown 構文を使っていることを確認します。詳細については、Daring Fireball の「Markdown: Syntax」(Markdown: 構文) を参照してください。

Missing docs folder

このエラーは、ブランチ上の docs フォルダーを発行元として選択したが、そのブランチのリポジトリのルートに docs フォルダーがないことを意味します。

トラブルシューティングを行うには、docs フォルダーが誤って移動された場合は、発行元用に選択したブランチのリポジトリのルートに docs フォルダーを戻してみてください。 docs フォルダーが誤って削除された場合は、次のいずれかを実行できます。

Git を使用して削除を revert する、つまり取り消す。詳細については、Git ドキュメントの「git-revert」を参照してください。
発行元用に選択したブランチのリポジトリのルートに新しい docs フォルダーを作成し、このフォルダーにサイトのソースファイルを追加する。詳しくは、「新しいファイルの作成」を参照してください。
公開ソースを変更する。詳しくは、「GitHub Pages サイトの公開元を設定する」を参照してください。

Missing submodule

このエラーは、存在しない、または適切に初期化されていないサブモジュールがリポジトリに含まれていることを意味します。

サブモジュールを使用しない場合は、サブモジュールを削除し、PATH-TO-SUBMODULE をサブモジュールへのパスに置き換えます。

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

サブモジュールを使用する必要がある場合は、そのサブモジュールを初期化します。詳細については、Pro Git ブックの「Git Tools - Submodules」(Git ツール - サブモジュール) を参照してください。

Relative permalinks configured

このエラーは、_config.yml ファイルに GitHub Pages でサポートされていない相対固定リンクがあることを意味します。

パーマリンクとは、サイトの特定ページを参照している恒久的な URL です。絶対パーマリンクはサイトのルートから始まり、相対パーマリンクは参照先ページを含むフォルダで始まります。 GitHub Pages と Jekyll では、相対パーマリンクがサポートされなくなっています。固定リンクの詳細については、Jekyll ドキュメントの「Permarinks」(固定リンク) を参照してください。

トラブルシューティングを行うには、relative_permalinks ファイルから _config.yml 行を削除し、サイト内の相対固定リンクを絶対固定リンクで再フォーマットします。詳しくは、「ファイルを編集する」を参照してください。

Syntax error in 'for' loop

このエラーは、コードの Liquid for ループ宣言に無効な構文が含まれていることを意味します。

トラブルシューティングを行うには、エラーメッセージ内のファイル内のすべての for ループに適切な構文があることを確認します。 for ループの適切な構文の詳細については、Liquid ドキュメントの「Iteration tags」(反復タグ) を参照してください。

Tag not properly closed

このエラーメッセージは、コードに含まれる論理タグが正しく閉じていないことを意味します。たとえば、{% capture example_variable %} は {% endcapture %} で閉じる必要があります。

トラブルシューティングするには、エラーメッセージで示されているファイルの論理タグがすべて適切に閉じられていることを確認します。詳細については、Liquid ドキュメントの「Liquid tags」(Liquid タグ) を参照してください。

Tag not properly terminated

このエラーは、正しく閉じられていない出力タグがコードに含まれていることを意味します。たとえば、{{ page.title }} ではなく {{ page.title } です。

トラブルシューティングを行うには、エラーメッセージ内のファイル内のすべての出力タグが }} で終了していることを確認します。詳細については、Liquid ドキュメントの「Liquid objects」(Liquid オブジェクト) を参照してください。

Unknown tag error

このエラーは、コードに認識されない Liquid タグが含まれていることを意味します。

トラブルシューティングするには、エラーメッセージで示されているファイルの Liquid タグがすべて Jekyll のデフォルトの変数に一致し、タグ名に誤入力がないことを確認します。既定の変数の一覧については、Jekyll ドキュメントの「Variables」(変数) を参照してください。

認識されないタグの主な原因は、サポート対象外のプラグインです。サイトをローカルで生成し、静的なファイルを GitHub にプッシュすることで、サポート対象外のプラグインを使用している場合は、そのプラグインで Jekyll のデフォルトの変数と異なるタグが使われていないかどうか確認してください。サポートされているプラグインの一覧については、「GitHub PagesとJekyllについて」をご覧ください。