If your GitHub Pages site fails to build on our servers or encounters other errors, you can troubleshoot your Jekyll build error by reviewing common problems or specific error messages. You can also view Jekyll build error messages by email, in your repository, on the command line, or using a third party service.
You will only receive an email if email support is enabled on your GitHub Enterprise instance. For more information, contact your GitHub Enterprise site administrator.
Viewing Jekyll build error messages
You can view Jekyll build error messages by email, in your repository, on the command line, or with a third-party service that displays error messages after each commit.
Generic Jekyll build failures
Generic build failures will not produce an email with specific file and error information. If you receive an email that simply says "Page build failed" with no further details, or your GitHub Pages site is not showing up after the first push, check for these common errors.
Page build failed: Invalid submodule
If your GitHub Pages code includes a reference to an invalid submodule, your GitHub Pages site will not build.
Page build failed: Missing submodule
If your GitHub Pages code includes a reference to a submodule that doesn't exist or hasn't been properly initialized, your GitHub Pages site will not build.
Page build failed: Markdown errors
If your GitHub Pages code contains Markdown errors, your GitHub Pages site will not build.
Page build failed: Config file error
If the _config.yml file in your GitHub Pages repository has syntax errors, your GitHub Pages site will not build.
Page build failed: Unknown tag error
If your GitHub Pages code contains an unrecognized Liquid tag, your GitHub Pages site will not build.
Page build failed: Tag not properly terminated
If your GitHub Pages code contains a Liquid output tag that is not properly terminated, your GitHub Pages site will not build.
Page build failed: Tag not properly closed
If your GitHub Pages code contains a Liquid logic tag that is not properly closed, your GitHub Pages site will not build.
Page build failed: File does not exist in includes directory
If your GitHub Pages code references a file that doesn't exist in your _includes directory, your GitHub Pages site will not build.
Page build failed: File is a symlink
If a file in your GitHub Pages repository references a symlinked file that does not exist in your repository, then your GitHub Pages site will not build.
Page build failed: Symlink does not exist within your site's repository
If your GitHub Pages site includes a symbolic link (also known as a symlink) to another file or directory that does not exist within your site's repository, your site will not build.
Page build failed: File is not properly UTF-8 encoded
If your GitHub Pages repository contains a file that is not properly UTF-8 encoded, your GitHub Pages site will not build.
Page build failed: Invalid post date
If your GitHub Pages repository contains a post with an invalid date, your GitHub Pages site will not build.
Migrating your Pages site from Maruku
Kramdown is Jekyll's default Markdown interpreter. The Maruku Markdown interpreter is considered obsolete. GitHub Pages Jekyll sites with invalid Markdown or HTML syntax may fail to build if you use the Maruku interpreter.
Files that start with an underscore are missing
If your GitHub Pages site isn't publishing certain files then you might need to reformat their titles. If you are using Jekyll you can create a .nojekyll file or edit the _config.yml file to publish these files.
