Adding a Custom Domain on Any Platform, and Why the Apex Is Different

Domain setup is presented as a three-step chore: point a record, wait, done. The steps are genuinely similar across platforms. What differs is the apex — the bare domain with no www — and that difference tells you something about how each platform handles DNS.

There is also one error worth knowing by heart, because it looks like a DNS propagation problem and is not.

The subdomain case is boring, which is good

For www.example.com or a similar subdomain, every platform documents the same instruction: create a CNAME pointing to the platform’s hostname.

• Cloudflare Pages: CNAME to <site>.pages.dev
• Netlify: CNAME to <site>.netlify.app
• Vercel: a per-project CNAME

A CNAME is legal on a subdomain by the DNS specification. Nothing surprising happens. If you only ever use www, the rest of this article does not apply to you.

The apex is where the platforms stop agreeing

The apex cannot accept a CNAME in standard DNS — a CNAME at the apex would conflict with the mandatory SOA and NS records. Each platform solves this differently, and the solutions are not interchangeable.

Platform	Apex method	Documented detail
Cloudflare Pages	CNAME flattening	Requires the domain to be a Cloudflare zone
Netlify	ALIAS/ANAME, or an A record	“apex domains don’t support CNAME records”
Vercel	A record	Apex and subdomain use different record types

Cloudflare’s approach is the most interesting, because it uses machinery you may already have. The documentation for CNAME flattening states that the feature “is also what allows you to use a root custom domain with a Cloudflare Pages site” — Cloudflare resolves the CNAME target and returns the final IP address instead of a CNAME record, which is legal at the apex.

For Pages specifically, there is a documented prerequisite: the domain must be a Cloudflare zone, with its nameservers pointed at Cloudflare. Given that, Cloudflare states it “will proceed by creating a CNAME record for you” — so the apex setup is largely automatic if your DNS is already on Cloudflare.

Netlify’s documentation puts the DNS constraint plainly: “Unlike subdomains, apex domains don’t support CNAME records.” Their documented options are an ALIAS, ANAME or flattened CNAME record pointing at their apex load balancer — which depends on your DNS provider supporting one of those types — or a plain A record to a specific IP.

That is a meaningful dependency. Not every DNS provider offers ALIAS or ANAME records, and none of those types are standard. If your DNS provider offers neither, the A record is your only path at the apex, and you have given up the flexibility a name-based record provides. (This is the same non-standard-record problem discussed in the CNAME article.)

Vercel documents an A record at the apex and a CNAME for subdomains — the simplest model, and the one that historically requires updating an IP if the provider changes it.

The error that is not a DNS problem

Here is the one to memorise. On Cloudflare Pages, the documented consequence of creating the CNAME yourself before associating the domain in the dashboard is:

“Manually adding a custom CNAME record… will result in your domain failing to resolve… and display a 522 error.”

A 522 is a connection timeout between the edge and the origin. If you see one after setting up a custom domain, the instinct is to wait for propagation or to check the record again. The actual cause is usually ordering: the platform has to know about the domain before the record is useful to it.

The fix is the documented procedure, in the documented order: add the domain in the platform’s dashboard first, then let it create or verify the record. For subdomains on some platforms, that ordering is invisible because the dashboard edits your zone for you. On Cloudflare Pages with an apex on a Cloudflare zone, it is also invisible. The error appears when you are on an external DNS provider and do the record first.

Certificate issuance depends on DNS being right first

SSL is automatic on all three platforms, and it is automatic conditionally. Certificate issuance happens after DNS resolves correctly, which means a DNS mistake shows up as a certificate problem rather than a DNS problem.

There is a documented case that is easy to miss: CAA records can block certificate issuance. If your domain publishes a CAA record naming specific certificate authorities, and the platform’s CA is not on the list, issuance fails. Cloudflare’s documentation for Pages’ custom domains names this explicitly as an interference point.

CAA is also inherited by subdomains and applies to the target of a CNAME, so a policy set for a different purpose can quietly block a new platform. If certificates are stuck and DNS looks correct, check CAA before anything else.

Domain ownership, and what verification does not mean

If a domain is already claimed on another account, the platforms handle it differently, and this is a documented gap worth knowing.

Vercel prompts you to add a TXT record to verify access to the domain. The documentation is careful about what that grants: verification permits you to use the domain — it does not transfer ownership of it. Two people can verify the same domain, and the verification is about proving control, not about who owns it.

Netlify shows a “Pending DNS verification” state in the interface and warns it “may take a full day for the settings to propagate” — a usefully specific expectation to set against the usual “a few minutes.”

Cloudflare Pages is the outlier here: I could not find documentation of a TXT ownership challenge or an explicit pending-certificate state for custom domains. Its documented failure modes are the 522 above and CAA interference. That does not mean no challenge exists — it means the behaviour is not written down, and you should verify your own setup rather than assume parity with the other two.

There is also a documented state change worth knowing: if you move DNS away from Cloudflare and back, the domain becomes inactive and has to be re-activated before it serves again.

The checklist

For any platform, in order:

1. Decide apex or www first. On Netlify, assigning one documents that both get added — check whether that is what you want.
2. Check your DNS provider supports what the apex method needs. ALIAS/ANAME support is not universal.
3. Add the domain in the platform dashboard before creating records on an external DNS provider.
4. Check CAA records if the domain has any, and confirm the platform’s CA is permitted.
5. Verify with a public resolver, not your laptop — the TTL article covers why.
6. Test the certificate, not just the page: curl -sI https://example.com/ and read the status and headers.

When to use the platform’s own DNS

If the platform also provides DNS, put the domain there. The apex works through the platform’s own mechanism, certificate issuance is the platform’s own workflow, and the ordering problem above cannot occur. The only reason to keep DNS elsewhere is that you need it elsewhere — mail on a different provider, a zone shared across services, or a registrar you do not want to move. Those are real reasons, and they come with the caveats above.