If your GitHub Pages site fails to build on our servers or encounters other errors, you can troubleshoot your 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.
Page build failed: Invalid Sass or SCSS
If your GitHub Pages repository contains a Sass or SCSS file with invalid content, your GitHub Pages site will not build.
Page build failed: Invalid highlighter language
If your GitHub Pages code uses the highlighter tag with an invalid language identifier, your GitHub Pages site will not build.
Updating your Markdown processor to kramdown
If you are not already using kramdown, Jekyll 3.0.0's default Markdown processor, then you must update your Markdown processor in your _config.yml file.
Page build failed: Relative permalinks
If you have relative permalinks set up in your _config.yml file, then you should receive a page build failure advising you to remove the relative_permalink option from your _config.yml file and replace any relative permalinks in your site with absolute permalinks.
Page build failed: Syntax error in 'for' loop
If your GitHub Pages code contains invalid syntax in the Liquid for loop declaration, your GitHub Pages site will not be built.
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.
