cloudflare / cloudflare/cloudflare-docs
Zone Holds: clarify that holds also block same-account operations (e.g. Pages custom domains)
- Dominant language
- MDX
- Stars
- 5.2k
- Forks
- 16.7k
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 337
Description
### Existing documentation URL(s)
- https://developers.cloudflare.com/fundamentals/account/account-security/zone-holds/
- https://developers.cloudflare.com/pages/configuration/debugging-pages/#zone-holds
- https://developers.cloudflare.com/pages/configuration/custom-domains/
### What changes are you suggesting?
There is an inconsistency in how the scope of Zone Holds is described across the documentation.
The main [Zone Holds page](https://developers.cloudflare.com/fundamentals/account/account-security/zone-holds/) says:
> Zone holds prevent other teams in your organization from adding zones that are already active in another account.
That wording strongly implies the restriction only applies to creating zones in *different* Cloudflare accounts.
However, the [Pages debugging documentation](https://developers.cloudflare.com/pages/configuration/debugging-pages/#zone-holds) states something broader:
> A zone hold will prevent Pages from adding a custom domain for a hostname under a zone hold.
>
> To add a custom domain for a hostname with a zone hold, temporarily release the zone hold during the custom domain setup process.
Note that it makes **no distinction between accounts**. In practice, the Pages custom-domain provisioning pipeline appears to consult the Zone Hold service regardless of whether the Pages project is in the same account as the held zone or in a different one.
**Suggested change:** update the Zone Holds page (and, if applicable, the "prevent subdomains" option description) to clarify that a zone hold does not only block zone creation in *other* accounts — it also blocks operations such as adding a Pages custom domain / custom hostname for a hostname under the hold, even within the same account. Alternatively, if same-account operations are *not* intended to be blocked, the Pages docs and product behavior should be reconciled accordingly.
**Why should the docs be changed?** As it stands, a reader of the Zone Holds page can reasonably conclude that a hold is safe to keep enabled while working within the same account, and then be surprised when Pages custom-domain setup fails. Clear wording about the actual scope of the hold would prevent this confusion.
**Expected outcome:** consistent wording across both pages that accurately describes which operations a zone hold blocks, and whether the account boundary matters.
### Additional information
This was discovered while debugging a Pages custom-domain setup that failed due to a zone hold within the same account. The [custom domains page](https://developers.cloudflare.com/pages/configuration/custom-domains/) also mentions releasing the zone hold before adding a custom domain, without an account distinction.
Contributor guide
Assessment
This issue has not been assessed yet.