cloudflare / cloudflare/cloudflare-docs

Zone Holds: clarify that holds also block same-account operations (e.g. Pages custom domains)

Open
#32,288 1 comment 1 reaction 7 assignees Claimed by @WalshyDev View on GitHub
product:fundamentals product:pages stale
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.