ビルドエラーのトラブルシューティング
Jekyll を使い、GitHub Pages サイトをローカルで、または GitHub 上でビルドしたときにエラーが発生した場合、エラー メッセージをトラブルシューティングに利用できます。 エラー メッセージとその表示方法の詳細については、「AUTOTITLE」を参照してください。
一般的なエラーメッセージが表示された場合は、よくある問題をチェックします。
- サポートされていないプラグインを使用している。 詳細については、「AUTOTITLE」を参照してください
- リポジトリがリポジトリサイズの制限を超えている。 詳細については、「AUTOTITLE」を参照してください
- ファイルの 設定を変更しました。 ブランチからサイトを公開している場合、この設定はビルド プロセス中に GitHub Pages によってオーバーライドされます。
- 公開元のファイル名にコロン () が含まれていますが、これはサポートされていません。
具体的なエラーメッセージが表示された場合は、エラーメッセージに関する以下のトラブルシューティング情報を確認してください。
エラーを修正したら、サイトのソース ブランチに変更をプッシュするか (ブランチから公開している場合)、またはカスタム GitHub Actions ワークフローをトリガーして (GitHub Actions で公開している場合)、別のビルドをトリガーします。
構成ファイル エラー
このエラーは、 ファイルに構文エラーが含まれているため、サイトのビルドに失敗したことを意味します。
トラブルシューティングを行うには、 ファイルが次のルールに従っていることを確認します。
- タブの代わりにスペースを使ってください。
timezone: Africa/Nairobiのように、キーと値の各ペアの:の後にスペースを含めます。- UTF-8キャラクタだけを使ってください。
:などの特殊文字は引用符で囲み、title: "my awesome site: an adventure in parse errors"のようにします。- 複数行の値の場合は、
|を使用して改行を作成し、>を使用して改行を無視します。
エラーを特定するには、YAML ファイルの内容をコピーし、YAML Validator などの YAML リンターに貼り付けます。
メモ
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 ドキュメント.
日付は有効な日時ではありません
このエラーは、サイトのいずれかのページに無効な日付データが含まれていることを意味します。
トラブルシューティングするには、エラーメッセージで示されたファイルおよびファイルのレイアウトで、日付関連の Liquid フィルタをコールしている箇所を探します。 日付関連の Liquid フィルターに渡される変数には、すべてのケースで値が含まれていることを確認し、 や を渡さないようにしてください。 詳細については、Liquid ドキュメントの「フィルター」を参照してください。
インクルード ディレクトリにファイルが存在しない
このエラーは、 ディレクトリに存在しないファイルをコードが参照していることを意味します。
トラブルシューティングを行うには、エラー メッセージで include のファイルを検索して、{% include example_header.html %} などの他のファイルを参照した場所を確認します。 参照したファイルのいずれかが ディレクトリにない場合は、ファイルを ディレクトリにコピーするか、移動します。
ファイルが正しく UTF-8 でエンコードされていない
このエラーは、これらの記号を期待するようコンピューターに伝えずに、などのラテン文字以外の文字を使用したことを意味します。
トラブルシューティングを行うには、 ファイルに次の行を追加して UTF-8 エンコードを強制します。
encoding: UTF-8
蛍光ペン言語が無効です
このエラーは、構成ファイルで Rouge または Pygments 以外の構文ハイライターを指定したことを意味します。
トラブルシューティングを行うには、 ファイルを更新して、Rouge または Pygments を指定します。 詳しくは、「AUTOTITLE」をご覧ください。
無効な投稿日
このエラーメッセージは、サイトでの投稿で、ファイル名または YAML フロントマターに無効な日付が含まれていることを意味します。
トラブルシューティングするには、日付がすべて YYYY-MM-DD HH:MM:SS 形式の UTC 時間で、実際のカレンダー日付であることを確認します。 UTC からのオフセットがあるタイム ゾーンを指定するには、 のような YYYY-MM-DD HH:MM:SS +/-TTTT 形式を使用します。
ファイルで日付形式を指定する場合は、形式が正しいことを確認してください。
Sass または SCSS が無効です
このエラーは、リポジトリに無効な内容の Sass または SCSS ファイルが含まれていることを意味します。
トラブルシューティングするには、エラーメッセージに含まれている行番号を確認して、無効な Sass または SCSS を探します。 今後のエラーを防ぐために、お好みのテキストエディター用の Sass または SCSS 文法チェッカーをインストールします。
無効なサブモジュール
このエラーは、適切に初期化されていないサブモジュールがリポジトリに含まれていることを意味します。
トラブルシューティングするために、まず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
サブ モジュールを使用する場合は、サブモジュールを参照するときに を使用し ( ではなく)、サブモジュールがパブリック リポジトリにあることを確認してください。
データ ファイルの YAML が無効です
このエラーは、_data フォルダー内のいずれかのファイルに無効な YAML が含まれていることを意味します。
トラブルシューティングを行うには、_data フォルダー内の YAML ファイルが次のルールに従っていることを確認します。
- タブの代わりにスペースを使ってください。
timezone: Africa/Nairobiのように、キーと値の各ペアの:の後にスペースを含めます。- UTF-8キャラクタだけを使ってください。
:などの特殊文字は引用符で囲み、title: "my awesome site: an adventure in parse errors"のようにします。- 複数行の値の場合は、
|を使用して改行を作成し、>を使用して改行を無視します。
エラーを特定するには、YAML ファイルの内容をコピーし、YAML Validator などの YAML リンターに貼り付けます。
Jekyll データ ファイルの詳細については、Jekyll ドキュメントの「データ ファイル」を参照してください。
マークダウン エラー
このエラーは、リポジトリ Markdown エラーがあることを意味します。
トラブルシューティングするには、必ずサポートされている Markdown プロセッサを使用するようにします。 詳しくは、「AUTOTITLE」をご覧ください。
次に、エラーメッセージで示されているファイルが有効な Markdown 構文を使っていることを確認します。 詳細については、Daring Fireball の「Markdown: 構文」を参照してください。
ドキュメント フォルダーがありません
このエラーは、ブランチ上の フォルダーを発行元として選択したが、そのブランチのリポジトリのルートに フォルダーがないことを意味します。
トラブルシューティングを行うには、 フォルダーが誤って移動された場合は、発行元用に選択したブランチのリポジトリのルートに フォルダーを戻してみてください。 フォルダーが誤って削除された場合は、次のいずれかを実行できます。
- Git を使用して削除を元に戻す。 詳細については、Git ドキュメントの「git-revert」を参照してください。
- 発行元用に選択したブランチのリポジトリのルートに新しい フォルダーを作成し、このフォルダーにサイトのソース ファイルを追加する。 詳しくは、「AUTOTITLE」をご覧ください。
- 公開ソースを変更する。 詳しくは、「AUTOTITLE」をご覧ください。
サブモジュールがありません
このエラーは、存在しない、または適切に初期化されていないサブモジュールがリポジトリに含まれていることを意味します。
トラブルシューティングするために、まず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 ツール - サブモジュール」を参照してください。
構成された相対パーマリンク
このエラーは、 ファイルに GitHub Pages でサポートされていない相対固定リンクがあることを意味します。
パーマリンクとは、サイトの特定ページを参照している恒久的な URL です。 絶対パーマリンクはサイトのルートから始まり、相対パーマリンクは参照先ページを含むフォルダで始まります。 GitHub Pages と Jekyll では、相対パーマリンクがサポートされなくなっています。 固定リンクの詳細については、Jekyll ドキュメントの「固定リンク」を参照してください。
トラブルシューティングを行うには、 ファイルから 行を削除し、サイト内の相対固定リンクを絶対固定リンクで再フォーマットします。 詳しくは、「AUTOTITLE」をご覧ください。
'for' ループの構文エラー
このエラーは、コードの Liquid ループ宣言に無効な構文が含まれていることを意味します。
トラブルシューティングを行うには、エラー メッセージ内のファイル内のすべての ループに適切な構文があることを確認します。 ループの適切な構文の詳細については、Liquid ドキュメントの「タグ」を参照してください。
タグが正しく閉じられない
このエラーメッセージは、コードに含まれる論理タグが正しく閉じていないことを意味します。 たとえば、 は で閉じる必要があります。
トラブルシューティングするには、エラーメッセージで示されているファイルの論理タグがすべて適切に閉じられていることを確認します。 詳細については、Liquid ドキュメントの「タグ」を参照してください。
タグが正しく終了しない
このエラーは、正しく閉じられていない出力タグがコードに含まれていることを意味します。 たとえば、 ではなく です。
トラブルシューティングを行うには、エラー メッセージ内のファイル内のすべての出力タグが で終了していることを確認します。 詳細については、Liquid ドキュメントの「オブジェクト」を参照してください。
不明なタグ エラー
このエラーは、コードに認識されない Liquid タグが含まれていることを意味します。
トラブルシューティングするには、エラーメッセージで示されているファイルの Liquid タグがすべて Jekyll のデフォルトの変数に一致し、タグ名に誤入力がないことを確認します。 既定の変数の一覧については、Jekyll ドキュメントの「変数」を参照してください。
認識されないタグの主な原因は、サポート対象外のプラグインです。 サポートされていないプラグインをサイトで使う場合は、サイトをローカルで生成し、静的ファイルを GitHub にプッシュすることで、Jekyll の既定の変数にないタグがそのプラグインによって追加されていないことを確認してください。 サポートされているプラグインの一覧については、「AUTOTITLE」を参照してください。