Troubleshooting GitHub Pages builds
GitHub Pages is available in public repositories with GitHub Free, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
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: Relative permalinks configured"
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.
"Page build failed: Invalid YAML in data file"
If one or more files in the _data folder of your GitHub Enterprise Pages site contains invalid YAML, your GitHub Enterprise Pages site will not build.
"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.