Add a Custom Domain to a Cloudflare Pages Site

How a Pages custom domain works

You connect a Cloudflare Pages project to your own domain in three steps. You add the hostname (the domain name of the site) in Pages. You add or confirm the DNS record. Then you wait until HTTPS is active. You can use the main address, also called the apex domain (example.com). You can also use a subdomain (reports.example.com), or the main address plus www.

Add the domain in Pages before you change DNS. A CNAME is a DNS record that points one name at another name. If a CNAME points at <project>.pages.dev but the project does not have the domain, the name does not resolve. Visitors then see a 522 error (Cloudflare custom domain docs).

Before you start

You need:

• A deployed Pages project that works at <project>.pages.dev. If your files are not live yet, first follow our Cloudflare Pages tutorial.
• A domain that you control, and access to its DNS settings.
• A decision about the address that visitors will use.

The correct location for your DNS depends on the address. In the table, a zone is a domain that Cloudflare runs DNS for. Nameservers are the servers that answer DNS lookups for a domain.

Address you want	Where DNS must be	Who creates the record
Apex domain, such as example.com	A Cloudflare zone on the same account as the Pages project, with Cloudflare’s nameservers	Cloudflare, once the nameservers point to it
Subdomain, zone already on Cloudflare	Cloudflare	Cloudflare adds the CNAME after you confirm it
Subdomain, DNS at another provider	Your current DNS provider	You add a CNAME to <project>.pages.dev

A subdomain such as reports.example.com can stay with your current DNS provider. For the apex domain, the domain must be on Cloudflare. A zone hold is a Cloudflare lock on a zone. If the zone is on the Cloudflare Enterprise plan and has a zone hold, release the hold during setup. The hold stops the subdomain from becoming active.

1. Add the hostname in Pages

1. In the Cloudflare dashboard, go to Workers & Pages. Select your Pages project.
2. Open Custom domains. Select Set up a domain.
3. Enter only the hostname, without https:// or a path. For example, enter reports.example.com, not https://reports.example.com/page.
4. Select Continue.

Cloudflare then shows the DNS values that it needs. Copy the values from this screen, not from an example.

2. Add or confirm the DNS record

If you use the apex domain, the domain must be a Cloudflare zone on the account that has the Pages project. Your registrar (the company where you bought the domain) must point to the Cloudflare nameservers (full setup). When the nameservers point to Cloudflare, Cloudflare creates the CNAME for you. Before you change the nameservers, make sure that the new Cloudflare zone has every record that you use today. This is most important for MX, SPF and other TXT verification records. If the zone that answers for your domain does not have those records, email stops working.

If you use a subdomain and the zone is on Cloudflare, confirm the DNS record that Cloudflare proposes. Cloudflare then adds the CNAME.

If you use a subdomain and your DNS is at a different provider, add this record at that provider:

Type	Name	Target
CNAME	reports	<project>.pages.dev

Some DNS providers automatically add your domain to the end of the Name field. With those providers, enter only reports. If you type the full hostname there, the provider creates reports.example.com.example.com. That name never resolves.

Cloudflare supports a CNAME at the root of a zone with CNAME flattening. Because of this, a public DNS lookup for the apex domain can return IP addresses and no visible CNAME. This alone does not mean that the record is wrong.

Change only the records for the website. Do not delete or overwrite MX records or verification TXT records while you work on the DNS for the website.

3. Wait for verification and HTTPS

When the DNS record exists, the domain shows Verifying. During this time, Cloudflare validates the domain and issues a certificate. Then the domain becomes active. DNS caching and certificate issuance can take some time. Look again after a few minutes. Do not delete the domain and create it again.

The Cloudflare Pages debugging guide recommends that you contact support if a domain still shows Verifying after 15 minutes. The guide names three common causes:

• Something blocks the HTTP validation check. An Access policy or a redirect on the hostname can stop the request that Cloudflare uses to validate the domain.
• CAA records (DNS records that list the allowed certificate authorities) do not allow the certificate authorities of Cloudflare. This cause is likely if you turned off Universal SSL or if you use an external DNS provider.
• A zone hold stops Pages from adding the hostname.

If your domain has CAA records, add these for both issue and issuewild:

Tag	Value
issue and issuewild	letsencrypt.org
issue and issuewild	pki.goog; cansignhttpexchanges=yes
issue and issuewild	ssl.com

If a domain has no CAA records, any certificate authority can issue certificates for it. In this case, you do not have to add CAA records.

4. Add www, or redirect it

The main domain and www are different hostnames. A working example.com does not make www.example.com work.

Choose one address as the main address. Redirect the other address to it. The Cloudflare www redirect guide uses Bulk Redirects to send www to the apex domain:

1. When example.com is attached to the Pages project, open Bulk Redirects in the Cloudflare dashboard.
2. Create a bulk redirect list with one entry: source www.example.com, target https://example.com, status 301. Turn on Preserve query string, Subpath matching, Preserve path suffix and Include subdomains.
3. Create a bulk redirect rule that uses that list.
4. In DNS, add an A record named www. Give it the IPv4 address 192.0.2.1 and the proxy status Proxied. 192.0.2.1 is a reserved documentation address (no real server uses it). The proxied record exists only so that Cloudflare can answer for www with the redirect.
5. After DNS updates, run curl --head -i https://www.example.com/. Make sure that the status is 301. Also make sure that the location header points to https://example.com/.

Alternatively, you can add www.example.com as a second custom domain in the project. Then both addresses serve the site. If you do this, choose one canonical address (the one main address that you publish) for links and search engines.

5. Redirect the pages.dev address (optional)

After you add a custom domain, the project stays reachable at <project>.pages.dev. To send visitors to your domain, use the same Bulk Redirects feature (pages.dev redirect guide). Add a list entry with source <project>.pages.dev, target https://example.com, status 301 and the same four options. Then add a rule that uses the list. After that, open <project>.pages.dev and make sure that it goes to your domain.

6. Check the result

Open the address over HTTPS in a private browser window. Then test:

• A nested page that you open directly by its URL, not only through the navigation
• An image, a stylesheet and a download
• The www address and the pages.dev address, if you redirected them
• The site on a phone

A custom domain does not make a site private

A domain changes the address. It does not change who can open the site. If the content needs a sign-in, protect every address that the project answers on. These are the custom domain, the pages.dev address and the preview address of each deployment. Our Cloudflare Pages Access guide shows the setup.

The order of the steps is important. Cloudflare does not let you add a custom domain that already has an Access policy (known issues). Attach the domain to Pages first, and then add Access. The same page warns that the domain can fail verification if Access does not allow the certificate validation path.

Troubleshooting

Symptom	Likely cause	Fix
522 error on the new domain	The CNAME exists, but the project does not have the domain	Add it under Custom domains > Set up a domain
Stuck on Verifying	Access or a redirect blocks validation, the CAA records are too strict, or a zone hold is on	Remove the block, add the CAA records above, or release the hold
Apex works, www does not	www is a separate hostname with no record	Add the redirect from step 4, or add www as a custom domain
Errors only on the custom domain, not on pages.dev	Proxied zone settings, such as caching, apply to the custom domain	To test, set the record to DNS only (gray cloud). Then review the zone settings
404 on the home page	No index.html at the top of the deployed folder	Deploy again with index.html at the root
Record name looks doubled	The DNS provider added the domain a second time	Enter only the label, such as reports

While you wait, keep the correct records in place. If you delete a pending domain and create it again, Cloudflare starts the work again from the beginning.

Remove a custom domain

In the DNS Records of the zone, find the CNAME that points to the Pages project. Select Edit > Delete. Then, in Workers & Pages, select the project and open Custom domains. Open the three-dot menu next to the domain, and then select Remove domain.

After that, the project answers only on its pages.dev address.

Free email addresses
for your AI agents

Each agent gets an address like myagent.x7k2@revdokumail.com. It can receive emails, send replies and store files.

• 3 free mailboxes, each with its own address
• 3,000 incoming and 500 sent emails a month
• 3 GB of storage for attachments and files
• Virus, malware, spam and prompt-injection filter
• Read and reply through API, MCP or CLI

Create free mailbox

You do not need a card.