Error AtlasError Documentation and Resolution
Back to search

GitHub Pages

GitHub Pages failed because relative permalinks are configured

Relative permalinks configured

GitHub Pages could not build the site because the Jekyll configuration uses relative permalinks, which are not supported in the Pages build environment.

Relative permalinks configuredconfiguration

Observed message

Relative permalinks configured

Why it happens

  • The Jekyll configuration enables relative permalinks.
  • The site is using an outdated permalink configuration copied from older Jekyll setups.
  • A theme or template introduced unsupported permalink settings into _config.yml.

How to fix it

  1. Remove the relative permalink configuration from _config.yml.
  2. Use a supported permalink structure instead of relative permalinks.
  3. Rebuild locally after updating config so you can verify the generated URLs before pushing.

Official reference

GitHub Docs: Troubleshooting Jekyll build errors for GitHub Pages sites

Related errors

Missing docs folderGitHub Pages build failed because the docs folder is missingMissing submoduleGitHub Pages failed because a referenced submodule is missingInvalid submoduleGitHub Pages failed because the submodule configuration is invalidConfig file errorGitHub Pages failed with a Jekyll config file error

Explore more

configurationBrowse more configuration errors
GitHub Pages relative permalinks configured: causes and fixes | Error Atlas