Cloudflare announced on January 23, 2026 that changing the type of an existing DNS record via the API is deprecated. End-of-life: June 30, 2026. After that date, a PATCH or PUT against /zones/{zone_id}/dns_records/{id} that flips a record's type field — A → CNAME, CNAME → A, TXT → MX — stops being supported.
The deprecation page doesn't promise a specific error code, just that "attempts to change a record's type via update operations will no longer be supported." Read that as: today it works, July 1 it doesn't, and the failure shape (4xx? 200 with success: false? silent partial?) won't be locked down until cutover.
If you're in the 90% of teams using the official Cloudflare Terraform provider on a recent version, you're probably fine — the provider already tags type as RequiresReplace, so it does delete-then-create on the client side (cloudflare/terraform-provider-cloudflare#6358). The teams that get bit are the ones running anything else against dns_records/{id} with a different type than what's in the record.
Where the breakage actually lives
Search your repos for direct DNS PATCH/PUT calls, not just Terraform configs:
git grep -nE "dns_records/[A-Za-z0-9]+" -- '*.py' '*.ts' '*.js' '*.go' '*.rb' '*.sh'
git grep -nE 'PATCH|PUT' -- '*.tf' '*.yaml' '*.yml' | grep -i dns
Common hiding spots:
-
OpenTofu / older Cloudflare provider forks. The
RequiresReplacemodifier landed in the schema rewrite — if you're pinned to a pre-v5 provider, you're still hitting the in-place PATCH path under the hood. -
Pulumi
cloudflare.Record. The Pulumi provider mirrors the upstream API's PATCH semantics for property updates. Confirm against your provider version that atypechange forces replacement, not update. -
CDK / SDK direct calls. Anything using
cloudflare-sdkor the rawrequests/fetch-against-the-REST-API pattern, where someone wrote a "reconciler" that PATCHes whatever fields differ. - Internal admin tools. That Slack bot you wrote to flip a hostname between origins. The internal "fix DNS" runbook in your wiki. The migration script your platform team kept after the last datacenter move.
-
CI jobs that re-apply DNS state. GitHub Actions workflows that call
cf-cli set-recordor equivalent and assume the API will figure out an in-place update.
The Cloudflare dashboard uses PATCH for type changes today, so anyone who reverse-engineered the dashboard's calls into a script (looking at you, "I just used the network tab") has a script that breaks on July 1.
Why "just delete and create" is a footgun
The naive migration path — delete the old record, create a new one with the new type — is correct for end-state but creates a non-zero NXDOMAIN window between the two API calls. Two consequences:
- Real DNS resolvers in the path will cache the NXDOMAIN. Most won't honor a TTL of zero on a negative answer. Mail servers in particular are aggressive negative cachers.
- Concurrent automation can race the gap. If your reconciler runs every 60 seconds and the create call fails for any reason — auth, rate limit, validation — you've left the zone with a missing record, and the next reconciliation will create the old type if the source-of-truth state hasn't propagated.
Don't do this naively. Use the Batch DNS records API.
The Batch DNS records API isn't a drop-in either
POST to /zones/{zone_id}/dns_records/batch with this shape:
{
"deletes": [{ "id": "old-record-id" }],
"patches": [],
"puts": [],
"posts": [
{
"name": "api.example.com",
"type": "CNAME",
"content": "lb.example.net",
"ttl": 300,
"proxied": true
}
]
}
The operations execute in a strict order: deletes → patches → puts → posts. That ordering matters more than it looks like it does.
Concrete example: you have an A record at api.example.com and want to flip it to CNAME api.example.com → lb.example.net. RFC 1912 prohibits a CNAME and an A record coexisting on the same hostname. If you tried to put the create first, Cloudflare would reject the new CNAME because the old A still exists. The fixed deletes-first ordering means batch requests for type changes always work, as long as you remember to put the old record in deletes and the new record in posts.
The batch is atomic at the database level — if any single operation fails, the whole transaction rolls back and you get the first error. It is not atomic at the edge. Cloudflare's blog explicitly calls this out: changes propagate through Quicksilver as independent key-value pairs, so resolvers may briefly see intermediate states during propagation. The window is short (low single-digit seconds), but it exists, and it's worse for high-volume zones because Quicksilver can serialize updates differently across colos.
If you have an SLA tighter than a few seconds of resolver inconsistency on the affected hostname, batch isn't enough either. You need the new hostname behind the new record on a different name during cutover, then swap upstream config to point at the new name.
Rate limits will surprise the largest scripts
The batch limits are different from the per-record API:
- Free plan: 200 operations per batch
- Paid plans: 3,500 operations per batch
If you have a migration script that walks 5,000 records and converts CNAMEs to A records (or vice-versa) and you're on the Free plan, it now needs to chunk by 200 with backoff. Cloudflare has tested batches up to 100,000 operations on enterprise tiers, so the ceiling exists, but it's tier-gated.
What the silent version of this failure looks like
The loud failure — Cloudflare returns 4xx after July 1 — is the easy case. Build red, fix forward.
The quieter failure is the migration to batch that subtly breaks something else.
-
Out-of-order operations in the same batch. If you submit
deletes: [A record]andposts: [A record with new type]to the same hostname, you're fine — order is fixed. But if you submitputsandpostson overlapping hostnames in one batch and the put fixes a different field, you can end up with surprising state because puts happen before posts. - Lost-write between source-of-truth and Cloudflare during the gap. Your reconciler runs at T=0, sees an A record, writes "I want CNAME" to source-of-truth at T=1, the batch fires at T=2, but a competing operator changed the source-of-truth to "I want TXT" at T=1.5. The batch happily deletes the A and creates a CNAME that's already stale.
- Edge cache poisoning during cutover. A high-traffic resolver hits the hostname during the propagation window, gets the old type, and caches it for full TTL. Subsequent queries from that resolver see a stale answer until the cache expires. SaaS API consumers caching DNS in-process (looking at you, JVM and Go's pre-1.19 default resolver) will see this for the full TTL.
These all work on a single integration test — the record is at the new type, GET returns the new shape — and only break under concurrent load or specific resolver paths.
Minimum-viable fix
-
git grepevery call site that PATCHes or PUTsdns_records/{id}and inventory which ones can changetype. - Bump the Cloudflare Terraform provider to a version with the schema rewrite (
typetaggedRequiresReplace). Do this in a non-prod zone first — you'll see a destroy-and-create plan for any record where TF state and Cloudflare diverge on type. - For non-Terraform paths, switch to
POST /zones/{zone_id}/dns_records/batchwith the old record indeletesand the new inposts. Wrap it so callers can't accidentally submit the same hostname inpostsandpatchessimultaneously. - Add a validation step in your reconciler: if
desired.type != current.type, route the change through batch, never through direct PATCH/PUT — even before the cutover. - Lower TTLs on records you expect to flip type on, before cutover, so the propagation window shrinks. 60-300s during migrations, restore after.
- Subscribe to Cloudflare's API deprecations RSS or page-monitor the deprecations page. Two more deprecations are likely to land before EOY.
The pattern this fits
Cloudflare's deprecation page is short and easy to miss. The change feels like a small migration ("just use batch"), and the batch API even existed for years before this announcement. But the failure surface is asymmetric — Terraform users barely notice, while anyone running a reconciler or admin tool against the legacy update endpoint will quietly start failing on July 1.
API contracts include the legal sequences of operations on a resource, not just the request/response shapes. "Update record type from A to CNAME" was a legal sequence today and isn't legal in two months. No SDK type system, schema diff, or contract test catches that, because the request shape is unchanged. The only signal is the deprecation note, and it gets read by the people writing IaC modules — not the people who wrote the admin tool three years ago and moved teams.
FlareCanary monitors REST APIs and MCP servers for schema drift. Free tier covers 5 endpoints with daily checks.
