Sometimes pages fail to build after a push and return the error "page build failed". There are a number of causes for this error.

Unverified email address

The Pages build process will not be triggered by a push if the user who pushed the commit doesn't have a verified email address.

Once you verify an email address, you'll need to make another push to trigger the Pages build process. You can also contact us so that we can manually run a build.

Unsafe plugins

The Pages server will not build with plugins that are not marked as safe. Note that this includes all plugins in the _plugins folder. There are two possible solutions to this problem:

  • Remove the unsafe plugins or
  • Build the pages locally and push the result files instead of the source files

The second option is the strategy used by Octopress.

Syntax errors

Sometimes the build fails because of typos or other errors in the source files. To ensure this is not the problem, install jekyll locally and build the pages using jekyll build --safe. You can find the version of jekyll used on our build server here.

Source setting

Our build server overrides the source setting when it builds your pages. If you change this setting, your pages may not build correctly.

Submodules in Pages

Does your repository have a submodule? We have a separate page on submodules with Pages detailing some common workarounds.

Viewing build error messages

To view build errors, simply run the jekyll build command locally.

Alternatively, you can configure a third-party service such as Travis CI to display error messages after each commit. This is usually accomplished in two steps.

First, so that the third-party knows you're using Jekyll, add a file named Gemfile to the root of your project with the following content (The "G" in Gemfile must be capitalized):

source 'https://rubygems.org'

gem 'github-pages'

Next, you need to configure your project for the testing service. To set up Travis, for example, you'd add a file named .travis.yml to the root of your project with the following content:

language: ruby
script: "bundle exec jekyll build"

Note: You may need to activate the Jekyll project within the third-party service before you can begin to receive feedback. In the Travis example above, you'd do so on your Travis CI profile page.

If you've vendored your Gems into a vendor folder (or a CI service like Travis has done it for you), be sure to add exclude: ["vendor"] to your _config.yml file to avoid potential conflicts.