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:
- Log in to the .
- In Account Home, go to Workers & Pages.
- In Overview, select your Pages project > View build.
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.
- Re-authorize your GitHub user/organisation 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 > Content 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 > Records 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.
Domain stuck in verification
Blocked HTTP validation
To check this, run a
curl command against your domain hitting
/.well-known/acme-challenge/randomstring. For example:
$ curl -I https://example.com/.well-known/acme-challenge/randomstringHTTP/2 302date: Mon, 03 Apr 2023 08:37:39 GMTlocation: https://example.cloudflareaccess.com/cdn-cgi/access/login/example.com?kid=...&redirect_url=%2F.well-known%2Facme-challenge%2F...access-control-allow-credentials: truecache-control: private, max-age=0, no-store, no-cache, must-revalidate, post-check=0, pre-check=0server: cloudflarecf-ray: 7b1ffdaa8ad60693-MAN
In the example above, you are redirecting to Cloudflare Access (as shown by the
Location header). In this case, you need to disable Access over the domain until the domain is verified. After the domain is verified, Access can be re-enabled.
You will need to do the same kind of thing for Redirect Rules or a Worker example too.
Missing CAA records
$ dig CAA example.com; <<>> DiG 9.10.6 <<>> CAA example.com;; global options: +cmd;; Got answer:;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 59018;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1;; OPT PSEUDOSECTION:; EDNS: version: 0, flags:; udp: 4096;; QUESTION SECTION:;example.com. IN CAA;; ANSWER SECTION:example.com. 300 IN CAA 0 issue "amazon.com";; Query time: 92 msec;; SERVER: 127.0.2.2#53(127.0.2.2);; WHEN: Mon Apr 03 10:15:51 BST 2023;; MSG SIZE rcvd: 76
In the above example, there is only a single CAA record which is allowing Amazon to issue ceritficates.
To resolve this, you will need to add the following CAA records which allows all of the Certificate Authorities (CAs) Cloudflare uses to issue certificates:
example.com. 300 IN CAA 0 issue "comodoca.com"example.com. 300 IN CAA 0 issue "digicert.com; cansignhttpexchanges=yes"example.com. 300 IN CAA 0 issue "letsencrypt.org"example.com. 300 IN CAA 0 issue "pki.goog; cansignhttpexchanges=yes"example.com. 300 IN CAA 0 issuewild "comodoca.com"example.com. 300 IN CAA 0 issuewild "digicert.com; cansignhttpexchanges=yes"example.com. 300 IN CAA 0 issuewild "letsencrypt.org"example.com. 300 IN CAA 0 issuewild "pki.goog; cansignhttpexchanges=yes"