Cloudflare Pages Custom Domain Setup

This guide is for teams that already have a Cloudflare Pages project and want a clean public hostname such as docs.example.com, preview.example.com, or handbook.example.com.

The order matters: associate the hostname with the Pages project first, then publish or confirm the DNS record. Cloudflare documents that manually pointing a CNAME at a pages.dev target without completing the Pages custom-domain flow can produce a 522 response.

If record types or the orange-cloud setting are unfamiliar, read Cloudflare DNS: Records, Proxy Status, and Verification before changing the active zone.

Choose the correct domain path

Cloudflare Pages treats these cases differently:

• Apex domain on Pages: example.com must be a zone in the same Cloudflare account, with its nameservers pointed to Cloudflare.
• Subdomain in a Cloudflare-managed zone: after you add and confirm the custom domain in Pages, Cloudflare can create the CNAME record in the zone for you.
• Subdomain using external DNS: add the domain in Pages, then create the CNAME at the authoritative DNS provider and point it to the exact <project>.pages.dev target.

Do not copy an apex setup onto a subdomain or assume that a record created in the DNS dashboard alone attaches the hostname to a Pages project.

1. Associate the hostname with the Pages project

In Workers & Pages, open the project, select Custom domains, and add the exact hostname. Confirm that you are editing the intended project before accepting any record change.

For an externally managed subdomain, the record has this shape:

Type: CNAME
Name: docs
Target: <project>.pages.dev

Use the target shown for your project. A similarly named project in another account is not interchangeable.

2. Verify the answer that your DNS mode should expose

The right command depends on who answers DNS and whether the record is proxied.

Cloudflare-managed, proxied record

Cloudflare flattens proxied CNAME records by default. Public DNS therefore returns Cloudflare Anycast addresses rather than the underlying pages.dev CNAME target:

dig docs.example.com A +short
dig docs.example.com AAAA +short

Seeing Cloudflare addresses here is expected. NXDOMAIN, or a response with neither A nor AAAA addresses, means the public record is not active yet. An empty AAAA answer by itself is not enough to diagnose failure, and a proxied record should not be expected to expose its underlying CNAME.

External DNS or a DNS-only CNAME

When the authoritative provider publishes the CNAME without Cloudflare proxying or provider-wide flattening, query the alias directly:

dig docs.example.com CNAME +short

Expected shape:

<project>.pages.dev.

If the provider flattens CNAMEs, use its documented behavior and compare A/AAAA answers instead. The important test is not forcing one record shape; it is confirming that the authoritative configuration matches the path Pages asked you to create.

Illustrative verification record

Illustrative example using reserved example domains and IPs.

3. Separate DNS, Pages activation, and HTTPS

After DNS answers, check the actual hostname:

curl -I https://docs.example.com

A healthy response usually starts like this:

HTTP/2 200
server: cloudflare
content-type: text/html; charset=utf-8

Interpret failures by layer:

• NXDOMAIN or no address answer: inspect the authoritative nameservers and active DNS record.
• 522 after a manually created Pages CNAME: confirm that the hostname was first associated through the Pages custom-domain flow.
• Pages shows the domain as pending: verify ownership, DNS, and certificate status before changing application code.
• Certificate issuance does not complete: inspect restrictive CAA records. The CAA guide explains why allowing only one certificate authority can block a managed platform.
• The correct hostname serves the wrong deployment: confirm the custom domain is attached to the intended Pages project and production branch.

If resolvers disagree after a change, use the cache-aware checks in DNS Propagation: TTLs, Caches, and Verification instead of repeatedly replacing the record.

Launch checklist

Before sharing the URL publicly, confirm:

• the hostname is attached to the intended Pages project
• DNS returns the expected answer for the record’s actual proxy mode
• curl -I returns a successful HTTPS response
• the browser shows a valid certificate for the exact hostname
• canonical links and redirects use the final hostname
• the old preview URL is no longer the primary link in docs

A Pages rollout is complete when the dashboard association, authoritative DNS behavior, certificate, and served deployment all agree. A visible CNAME is not a required success signal for a proxied Cloudflare record.