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.

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: Missing docs folder

If you have the master branch /docs folder source setting enabled and your /docs folder with your site's source files was removed from the root of your repository on the master branch, your GitHub Pages site will not build.

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: Date is not a valid datetime

If your GitHub Pages repository contains a page which displays an invalid datetime, your GitHub Pages site will not build.

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.