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.

If your GitHub Pages site fails to build because of a reference to a symlinked file, you'll get an email that looks like this:

Subject: Page build failed

The page build failed with the following error:

A file was included in `example.html` that is a symlink or does not exist in your `_includes` directory.

You will only receive an email if outbound email support is enabled on your Enterprise instance. For more information, contact your site administrator.

Troubleshooting a symlinked file error

Tip: We strongly recommend running Jekyll locally so you can easily debug and fix build errors before pushing to your GitHub Enterprise instance. To learn more about troubleshooting options, see "Troubleshooting Jekyll builds."

  1. Use your favorite text editor to open the file mentioned in the build failure email.
  2. Search for the include tag to see where you've referenced other files. For example: {% include cool_header.html %}.
  3. Copy or move any symlinked files into the _includes directory of your GitHub Pages repository.
  4. Commit and push to your GitHub Pages repository on your GitHub Enterprise instance to trigger another build on the server.