Troubleshooting GitHub Pages builds

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.

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.

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.

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.

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.