When setting up your Pages project, you may encounter various errors that prevent you from successfully deploying your site. This guide gives an overview of some common errors and solutions.
Check your build log
You can review build errors in your Pages build log. To access your build log:
Possible errors in your build log are included in the following sections.
Initializing build environment
Possible errors in this step could be caused by improper installation during git integration.
To fix this in GitHub:
- Log in to your Github account.
- Go to Settings from your user icon > find Applications under Integrations.
- Find Cloudflare Pages > Configure > scroll down and select Uninstall.
- Readd the repository on the Cloudflare dashboard.
To fix this in GitLab:
- Log in to your GitLab account.
- Go to Preferences from your user icon > Applications.
- Find Cloudflare Pages > scroll down and select Revoke.
Be aware that you need a role of Maintainer or above to successfully link your repository, otherwise the build will fail.
Cloning git repository
Make sure to also review your submodule configuration by going to the
.gitmodules file in your root directory. This file needs to contain both a
path and a
Example of a valid configuration:
[submodule "example"]path = example/pathurl = git://github.com/example/repo.git
Example of an invalid configuration:
[submodule "example"]path = example/path
[submodule "example"]url = git://github.com/example/repo.git
Possible errors in this step could be caused by faulty setup in your Pages project. Review your build command, output folder and environment variables for any incorrect configuration.
Deploying to Cloudflare’s global network
pages.dev and custom domains
If your custom domain is proxied (orange-clouded) through Cloudflare, your zone’s settings such as Auto Minify and caching will apply.
If you are experiencing issues with a framework, like Nuxt.js, only on the custom domain, review if Auto Minify is enabled (log in to the > Speed > Optimization > Auto Minify) for HTML and disable it.
If you are experiencing issues with new content not being shown, go to Rules > Page Rules in the Cloudflare dashboard and check for a Page Rule with Cache Everything enabled. If present, remove this rule as Pages handles its own cache.
If you are experiencing errors on your custom domain but not on your
pages.dev domain, go to DNS in the Cloudflare dashboard and set the DNS record for your project to be DNS Only (grey cloud). If the error persists, review your zone’s configuration.