A Pages custom domain added by API gets stuck on 'CNAME record not set'

The symptom

I attached a custom domain to a Cloudflare Pages project over the API (POST /accounts/{id}/pages/projects/{name}/domains). It returned success, then sat at status: pending indefinitely. DNS resolved to Cloudflare, and the site returned a 522. The domain detail said it plainly: verification_data.error_message: "CNAME record not set".

What was happening

When you add a custom domain to a Pages project in the dashboard, Cloudflare does two things: it registers the domain with the project, and it creates the DNS record that points the domain at the project, a flattened CNAME to <project>.pages.dev. The API call only does the first. The domain is attached and nothing in DNS routes to the project, hence “CNAME record not set” and the 522, where DNS reaches Cloudflare’s edge and finds no origin behind it.

Token scope adds a second layer. A Pages-only API token can attach the domain but cannot create the DNS record, which needs Zone > DNS > Edit, a different permission. So even when you script it, the Pages token gets you halfway and stops.

The fix

Create the DNS record yourself with a token that has DNS edit on the zone. For an apex domain whose zone is in the same Cloudflare account:

curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \
  -H "Authorization: Bearer $DNS_EDIT_TOKEN" -H "Content-Type: application/json" \
  --data '{"type":"CNAME","name":"example.com","content":"my-project.pages.dev","proxied":true,"ttl":1}'

Cloudflare flattens the apex CNAME automatically. Once the record exists, the Pages domain re-validates from pending to active within a minute or two and the 522 clears. Adding the domain through the dashboard does both steps in one click, which is why the dashboard works and the bare API call does not.

The lesson

“Add a custom domain” in the Pages dashboard is two actions, registering the domain and creating its DNS record. The API only registers it, and a Pages-scoped token cannot create the DNS. If a Pages custom domain is stuck on “CNAME record not set”, add the CNAME yourself with a DNS-edit token and it goes active.