Sometimes pages fail to build after a push and return the error "page build failed". There are a number of causes for this error.
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.
The Pages server will not build with plugins that are not marked as safe. Note that this includes all plugins in the
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.
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.
Our build server overrides the
source setting when it builds your pages. If you change this setting, your pages may not build correctly.
Does your repository have a submodule? We have a separate page on submodules with Pages detailing some common workarounds.
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.