ビルドエラーのトラブルシューティング
GitHub Pages サイトをローカルで、または GitHub Enterprise Server 上でビルドしているときに Jekyll でエラーが発生した場合、そのエラーメッセージをトラブルシューティングに利用できます。 エラーメッセージとその見方に関する詳しい情報は、「GitHub Pages サイトのJekyllビルドエラーについて」を参照してください。
一般的なエラーメッセージが表示された場合は、よくある問題をチェックします。
- サポートされていないプラグインを使用している。 詳しい情報については、「GitHub Pages と Jekyll について」を参照してください。
- _config.yml ファイルで
source
の設定を変更した。 ビルドプロセス中に、この設定は GitHub Pages によってオーバーライドされます。 - 公開ソースにあるファイル名にコロン (
:
) が含まれている。コロンは使用できません。
具体的なエラーメッセージが表示された場合は、エラーメッセージに関する以下のトラブルシューティング情報を確認してください。
エラーを修正したら、ソースを公開しているサイトにその変更をプッシュし、GitHub Enterprise Server でもう一度ビルドを実行します。
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文法チェッカーに貼り付けてください。
Date is not a valid datetime
このエラーは、サイトのいずれかのページに無効な日付データが含まれていることを意味します。
トラブルシューティングするには、エラーメッセージで示されたファイルおよびファイルのレイアウトで、日付関連の Liquid フィルタをコールしている箇所を探します。 日付関連の Liquid フィルタに渡される変数に、すべてのケースで値があることと、nil
または ""
を渡していないことを確認します。 詳細は、Liquid のドキュメンテーションで「Liquid フィルタ」を参照してください。
File does not exist in includes directory
このエラーは、_includes ディレクトリに存在していないファイルをコードで参照していることを意味します。
トラブルシューティングするために、たとえば{% include example_header.html %}
といった他のファイルを参照しているところを見るために、エラーメッセージ中のファイルでinclude
を検索してください。 参照していたファイルのいずれかが _includes ディレクトリに存在しない場合は、そのファイルを _includes ディレクトリにコピーまたは移動してください。
File is a symlink
このエラーは、サイトの公開ソースに存在しないシンボリックリンクされたファイルをコードで参照していることを意味します。
トラブルシューティングするために、たとえば{% include example_header.html %}
といった他のファイルを参照しているところを見るために、エラーメッセージ中のファイルでinclude
を検索してください。 参照していたファイルのいずれかがシンボリックリンクされている場合は、そのファイルを _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 Enterprise Server と Jekyll について」を参照してください。
Invalid post date
このエラーメッセージは、サイトでの投稿で、ファイル名または YAML フロントマターに無効な日付が含まれていることを意味します。
トラブルシューティングするには、日付がすべて YYYY-MM-DD HH:MM:SS 形式の UTC 時間で、実際のカレンダー日付であることを確認します。 UTC との時差があるタイムゾーンを指定する場合は、YYYY-MM-DD HH:MM:SS +/-TTTT 形式を使用し、たとえば 2014-04-18 11:30:00 +0800
のように指定します。
_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 フォルダの 1 つ以上のファイルに無効な YAML が含まれていることを意味します。
トラブルシューティングするには、_data フォルダの YAML ファイルが次のルールに従っていることを確認します。
- タブの代わりにスペースを使ってください。
timezone: Africa/Nairobi
のように、各キーと値のペアで:
の後にはスペースを入れてください。- UTF-8キャラクタだけを使ってください。
title: "my awesome site: an adventure in parse errors"
といったように、:
などの特別なキャラクタはダブルクオートで囲んでください。- 複数行にわたる値については、改行の作成に
|
を、改行を無視するためには>
を使ってください。
エラーがあるかを調べるには、YAMLファイルの内容をコピーし、YAML ValidatorなどのYAML文法チェッカーに貼り付けてください。
Jekyll データファイルの詳細は、Jekyll のドキュメンテーションで「データファイル」を参照してください。
Markdown errors
このエラーは、リポジトリ Markdown エラーがあることを意味します。
トラブルシューティングするには、必ずサポートされている Markdown プロセッサを使用するようにします。 詳細は、「Jekyll を使用して、GitHub Pages サイトの Markdown プロセッサを設定する」を参照してください。
次に、エラーメッセージで示されているファイルが有効な Markdown 構文を使っていることを確認します。 詳細は、Daring Fireball の「Markdown: 構文」を参照してください。
Missing docs folder
このエラーは、公開元としてブランチの docs
フォルダを選択したが、そのブランチのリポジトリのルートに docs
フォルダがないことを意味します。
トラブルシューティングをするには、docs
フォルダが誤って移動された場合は、公開元向けに選択したブランチのリポジトリのルートに docs
フォルダを戻してみます。 docs
フォルダを誤って削除した場合は、次のいずれかの方法が可能です。
- Git を使用して削除を revert する、つまり取り消す。 詳細は、Git のドキュメンテーションで「git-revert」を参照してください。
- 公開元向けに選択したブランチのリポジトリのルートに新しい
docs
フォルダを作成し、サイトのソースファイルをフォルダに追加します。 詳細は「新しいファイルを作成する」を参照してください。 - 公開ソースを変更する。 詳細は「GitHub Pages の公開ソースを設定する」を参照してください。
Missing 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
サブモジュールを使用する必要がある場合は、そのサブモジュールを初期化します。 詳細は、Pro Git ブックで「Git Tools - Submodules」を参照してください。
Relative permalinks configured
このエラーは、_config.yml ファイルで相対パーマリンクを使用していることを意味します。相対パーマリンクは GitHub Pages でサポートされていません。
パーマリンクとは、サイトの特定ページを参照している恒久的な URL です。 絶対パーマリンクはサイトのルートから始まり、相対パーマリンクは参照先ページを含むフォルダで始まります。 GitHub Pages と Jekyll では、相対パーマリンクがサポートされなくなっています。 詳細は、Jekyll のドキュメンテーションで「パーマリンク」を参照してください。
トラブルシューティングするには、_config.yml ファイルから relative_permalinks
の行を削除し、サイトに相対パーマリンクがある場合は絶対パーマリンクに直します。 For more information, see "Editing files."
Symlink does not exist within your site's repository
このエラーは、サイトの公開ソースに存在しないシンボリックリンク (symlink) がサイトに含まれていることを意味します。 シンボリックリンクの詳細は、Wikipedia で「Symbolic link」を参照してください。
トラブルシューティングするには、エラーメッセージで示されているファイルがサイトのビルドに使われているかどうかを確認します。 使われていない場合、またはファイルをシンボリックリンクにしたくない場合は、ファイルを削除します。 サイトのビルドにシンボリックファイルが必要な場合は、そのシンボリックリンクで参照されているファイルまたはディレクトリが、サイトの公開ソースにあることを確認してください。 外部アセットを除外するには、サードパーティのパッケージマネージャー、たとえば Bower などの使用を検討します。
Syntax error in 'for' loop
このエラーは、 Liquid の for
ループ宣言で無効な構文が含まれていることを意味します。
トラブルシューティングするには、エラーメッセージで示されているファイルですべての for
ループの構文が正しいことを確認します。 for
ループの正しい構文についての詳しい情報は、Liquid のドキュメンテーションで「反復タグ」を参照してください。
Tag not properly closed
このエラーメッセージは、コードに含まれる論理タグが正しく閉じていないことを意味します。 たとえば、{% capture example_variable %}
は {% endcapture %}
で閉じる必要があります。
トラブルシューティングするには、エラーメッセージで示されているファイルの論理タグがすべて適切に閉じられていることを確認します。 詳細は、Liquid のドキュメンテーションで「Liquid タグ」を参照してください。
Tag not properly terminated
このエラーは、正しく閉じられていない出力タグがコードに含まれていることを意味します。 たとえば、{{ page.title }}
となるはずが {{ page.title }
となっているような場合です。
トラブルシューティングするには、エラーメッセージで示されているファイルの出力タグがすべて }}
で適切に閉じられていることを確認します。 詳細は、Liquid のドキュメンテーションで「Liquid オブジェクト」を参照してください。
Unknown tag error
このエラーは、コードに認識されない Liquid タグが含まれていることを意味します。
トラブルシューティングするには、エラーメッセージで示されているファイルの Liquid タグがすべて Jekyll のデフォルトの変数に一致し、タグ名に誤入力がないことを確認します。 デフォルトの変数のリストは、Jekyll のドキュメントで「変数」を参照してください。
認識されないタグの主な原因は、サポート対象外のプラグインです。 サイトをローカルで生成し、静的なファイルを GitHub Enterprise Server にプッシュすることで、サポート対象外のプラグインを使用している場合は、そのプラグインで Jekyll のデフォルトの変数と異なるタグが使われていないかどうか確認してください。 サポート対象のプラグインについては、「GitHub Pages と Jekyll について」を参照してください。