DNS: rewrite Pending Nameserver Update troubleshooting for the common case - #32157
Merged
ngayerie merged 20 commits intoJul 29, 2026
Merged
Conversation
ngayerie
requested review from
a team,
Woutifier,
chreo,
dklbreitling,
esomoza-cf,
hannes-cf,
kerolasa,
matildeopbravo,
svenr-cf,
vendemiat and
xofyarg
as code owners
July 20, 2026 10:05
Contributor
Review
👉 Fix in your agent 👈Fix the following review findings in PR #32157 (https://github.com/cloudflare/cloudflare-docs/pull/32157).
Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order
After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.
The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.
---
## Style Guide Review
### Warnings (1)
#### SG-d72005e4c1cb · DNS record types should use monospace
- **File:** `src/content/docs/dns/zone-setups/partial-setup/setup.mdx` line 81
- **Issue:** Line contains "verification TXT record" in prose, with the DNS record type `TXT` unmonospaced.
- **Fix:** Change to "verification `TXT` record".
### Suggestions (2)
#### SG-3479eacddd0d · Avoid 'etc.' in prose
- **File:** `src/content/docs/dns/zone-setups/troubleshooting/pending-nameservers.mdx` line 57
- **Issue:** Line adds '(`com.`, `co.uk.`, etc.)' in a bullet explaining parent zones.
- **Fix:** Replace 'etc.' with a complete list or 'and so on'.
#### SG-8fb0e29cbcef · Avoid 'see [link]'; use 'refer to [link]'
- **File:** `src/content/docs/dns/zone-setups/troubleshooting/pending-nameservers.mdx` line 63
- **Issue:** Line adds '...see [Step 4](#4-check-for-stale-dnssec-ds-records)...'
- **Fix:** Change to 'refer to [Step 4](#4-check-for-stale-dnssec-ds-records)'.
Code ReviewThis code review is in beta and may not always be helpful — use your judgment. No code review issues found. ConventionsNo convention issues found. Style Guide ReviewWarnings (1)
Suggestions (2)
CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
github-actions
Bot
assigned
chreo,
dklbreitling,
esomoza-cf,
hannes-cf,
kerolasa,
matildeopbravo,
svenr-cf,
vendemiat,
Woutifier and
xofyarg
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Collaborator
Author
Bot review triageCR-50739f080263 — Foundation DNS nameserver count: ✅ Agree, fixed. Foundation DNS advanced nameservers assign three nameserver hostnames (one each in
Fixed in the follow-up commit by:
|
Contributor
|
Nimbus Preview URL: https://nimbus-94dce313.preview.developers.cloudflare.com |
Contributor
Collaborator
Author
Bot review triage (commit
|
hannes-cf
reviewed
Jul 21, 2026
matildeopbravo
requested changes
Jul 24, 2026
ngayerie
force-pushed
the
dns-pending-nameservers-generic-troubleshooting
branch
from
July 27, 2026 14:27
19d4d5e to
c83f0fc
Compare
… case Rewrite /dns/zone-setups/troubleshooting/pending-nameservers/ around the actual most-common failure modes seen in support: parent-zone delegation mismatches, wrong Cloudflare NS pair, or registrar not publishing the change. Stale DNSSEC DS records remain covered as one step (Step 4) rather than the article's opening frame. New flow: - Confirm the assigned Cloudflare nameservers - Check what the parent zone actually publishes (dig +trace, nslookup, and web-based lookups via digwebinterface.com and whatsmydns.net) with a result-driven action table - Verify the change was saved at the registrar (covers transfer/lock states, wrong-account edits, registrar propagation, resellers) - Check for stale DNSSEC DS records - What to attach to a support ticket if the zone is still Pending Cross-links added so this article becomes the canonical troubleshooting entry point: - Callout at the top of full-setup/troubleshooting.mdx - Extended existing note in full-setup/setup.mdx Step 3.5 - New note in partial-setup/setup.mdx Step 2 for TXT-verification zones - Cross-link from the DNS FAQ nameserver answer
…formats in Step 1
Address code-review finding CR-50739f080263: Foundation DNS advanced nameservers assign three nameserver names (one each in .com, .net, .org), not one of three. Adjust Step 1 to show a per-setup count column, and reword phrases like 'the pair' / 'the two nameservers' to work for all setups (full, Foundation DNS, secondary, and custom nameservers).
…parent zone Address code-review findings CR-fed534616f69 and CR-f8c992b6d91e: the previous wording implied -debug forces an authoritative parent-zone response, which it does not. Clarify that -debug only exposes the full response detail, and add a second nslookup example that targets a TLD nameserver directly, which is the true equivalent of dig +trace. Also show how to find the authoritative TLD nameservers for any extension.
- pending-nameservers.mdx: 'hostname format' -> 'name format' throughout Step 1 intro, table header, and custom nameservers row. - partial-setup/setup.mdx: TXT verification record lives at cloudflare-verify.<YOUR_DOMAIN>, not at the apex.
Cloudflare Registrar customers cannot freely change assigned nameservers from the Domain Registration configuration UI, so that pointer was wrong and misleading. Drop the sentence entirely; the surrounding step already explains what to check at the registrar in general terms.
- Correctness: rework the nameserver-assignment paragraph. Cloudflare favors consistent nameservers across zones in the same account; only conflicts or a different nameserver type cause a different assignment. The previous 'each zone gets its own set' phrasing contradicted the authoritative /dns/nameservers/nameserver-options/#assignment-method page. - Style: 'Option C - web-based lookup' (sentence case). - Style: add a full introductory sentence with a colon before the 'What to do based on the result' table. - Style: split the semicolon-joined clauses about activation checks into two sentences.
Follow-up to 3a18dba, adding two edits that did not sync in time on the previous commit: - Correctness: rework the nameserver-assignment paragraph. Cloudflare favors consistent nameservers across zones in the same account; only conflicts (same domain added to another account) or a different nameserver type cause a different assignment. The previous 'each zone gets its own set' phrasing contradicted the authoritative /dns/nameservers/nameserver-options/#assignment-method page. - Style: add an introductory sentence before the 'What to do based on the result' table.
- Capitalise 'Internet' as a proper noun per Cloudflare style guide. - Rewrite passive voice in partial-setup callout to active voice: 'confirm the record is served by your authoritative DNS provider' -> 'confirm your authoritative DNS provider serves the record'.
- full-setup/troubleshooting.mdx: drop the '(including dig +trace, nslookup, and web-based lookup tools)' parenthetical from the callout. The linked article already documents these tools; listing them again here is redundant. - partial-setup/setup.mdx: drop the third-party tool suggestions (digwebinterface.com, whatsmydns.net) from the callout. Keep the local dig example and defer to the main troubleshooting article for the full toolset. Sidesteps the third-party-site linking question at a callout level while keeping the tools in the main article, where they're explicitly needed for the parent-zone check.
…tup callout Reverts the partial half of b8b4e02. The full-setup troubleshooting callout keeps the trimmed wording. Third-party links to digwebinterface.com and whatsmydns.net are already an established pattern across DNS docs (dns/faq, dns/dnssec/dnssec-active-migration, dns/zone-setups/full-setup/ setup, dns/zone-setups/troubleshooting/cannot-add-domain, and others), so keeping them in this callout for consistency.
Address Sven's review comment: typos like 'cloudlfare.com' and 'cloudfare.com' are a common failure mode that leaves the zone in Pending Nameserver Update. Add a caution callout at the end of Step 1 telling customers to copy the values directly from the dashboard rather than typing them.
- Options A + B: hint that these are terminal commands ('In a terminal,
run:') so readers who are unfamiliar with dig/nslookup know the
context. (Comment 3644340257.)
- Option B nslookup section: drop the 'find TLD nameservers with dig NS
com.' instruction — a customer who is on nslookup precisely because
they don't have dig can't use that. Point at IANA's root zone
database instead. (Comment 3644335950.)
- Action table: drop 'or Cloudflare as Secondary DNS' from the
Cloudflare+other-provider row. Multi-provider is what actually counts
here; Secondary zones happen to enable it but are not the primary
case. (Comment 3644356050.)
- Step 5: don't claim the activation-check endpoint can be called 'at
any time'. It is rate-limited, may return an error, and even on
success only queues the check — completion can still take minutes
to hours. (Comment 3644372811.)
Follow-up to 20f7e5f — three edits did not sync into that commit: - Options A and B: prefix with 'In a terminal, run:' so readers understand these are shell commands. (Comment 3644340257.) - Option B: replace the 'find TLD nameservers with dig NS com.' line — a customer on nslookup because they lack dig cannot use it. Point at IANA's root zone database instead. (Comment 3644335950.) - Option A intro: drop 'or Cloudflare as Secondary DNS' alongside the parallel edit already made to the action table. (Comment 3644356050.)
- Nameserver name format table: replace 'NAME' placeholder with the repo-standard placeholders — '<proper_name>' for standard and secondary nameservers (matches dns/nameservers/index.mdx line 35) and '<color>' for Foundation DNS advanced nameservers (matches dns/nameservers/index.mdx line 45). (Comment 3645012696.) - DNSSEC step: replace vague 'resolvers will refuse the new nameservers' with the concrete failure mode — 'the DNSSEC chain of trust breaks and resolvers return SERVFAIL for your domain'. (Comment 3644937706.) - Step 5 timing: drop the overloaded 'DNS propagation' phrasing. Reword to say activation timing depends on when the recheck runs and on whether the registrar change has taken effect by then. (Comment 3644868566.)
Follow-up to 2faca55 — the placeholder rename didn't land in that commit (edit tool couldn't match the long table row exactly). Apply via sed: - Standard full setup: 'NAME.ns.cloudflare.com' -> '<proper_name>.ns. cloudflare.com' (matches dns/nameservers/index.mdx line 35). - Foundation DNS: 'NAME.foundationdns.{com,net,org}' -> '<color>. foundationdns.{com,net,org}' (matches dns/nameservers/index.mdx line 45). - Secondary DNS: 'NAME.secondary.cloudflare.com' -> '<proper_name>. secondary.cloudflare.com'. - Custom nameservers: 'Your own branded hostnames' -> 'Your own branded names' (consistent with the new 'Nameserver name format' column header). Fixes Matilde review comment 3645012696.
ngayerie
force-pushed
the
dns-pending-nameservers-generic-troubleshooting
branch
from
July 28, 2026 13:54
c83f0fc to
6ad1adb
Compare
- Intro line: 'the exact nameserver pair assigned to it' -> 'the exact nameservers assigned to it'. Foundation DNS assigns three, not two, so 'pair' does not fit all cases. (Comment 3666822457.) - Step 1: drop the 'each zone gets its own set / tied to your account' sentence and add a dedicated note explaining WHY the assigned nameservers can differ from what the customer expected — pre-existing Cloudflare delegation at zone-add time, or re-adding a deleted domain, triggers a fresh assignment to prevent domain hijacking. Also reinforces the 'update the delegation after creating the zone' order of operations. (Comment 3666822479, applied verbatim.) Not addressing comment 3666822471 (dig +trace) in this commit — that warrants further discussion with the reviewer.
Follow-up to 655d238: Option C also said 'nameserver pair', which does not fit Foundation DNS's 3-nameserver assignment. Reword to 'the nameservers' for consistency.
matildeopbravo
self-requested a review
July 28, 2026 16:13
…dback - Replace 'dig +trace example.com NS' with 'dig +trace example.com NS +noall +authority +nodnssec' — the extra flags trim the output to the authority section, which is what the reader actually needs. - Add a bulleted explanation of each flag (+trace, +noall +authority, +nodnssec). - Change 'last section' to 'last non-empty section' — with +noall +authority the last dig block can be empty for the target zone. - Add a caution callout explaining that +nodnssec hides DS records and pointing the reader at Step 4 to re-check without the flag. (Matilde comment 3667115163.)
matildeopbravo
approved these changes
Jul 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
11 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewrite
/dns/zone-setups/troubleshooting/pending-nameservers/around the actual most-common failure modes we see in support — parent-zone delegation mismatches, wrong Cloudflare nameserver pair, or the registrar not publishing the change. Stale DNSSEC DS records remain covered, but as one step (Step 4) rather than the article's opening frame.Why
The current article opens with DNSSEC as "the most common cause," but the Salesforce and Community evidence over the last 60 days is dominated by cases where the parent zone simply is not delegating to the assigned Cloudflare nameservers — the customer's registrar UI showed the right values, but the parent zone was still returning something else. Customers had no guidance in the docs on how to check what the parent zone actually publishes.
New troubleshooting flow
dig +trace <domain> NSnslookup -type=ns <domain>Followed by a result-driven action table (correct pair / wrong pair / other provider / none / mixed).
Consolidation
This PR also adds three light cross-links so the rewritten article becomes the canonical troubleshooting entry point:
dns/zone-setups/full-setup/troubleshooting.mdx— new callout at the top pointing to the pending-nameservers article.dns/zone-setups/full-setup/setup.mdx— extends the existing troubleshooting note in the nameserver-change step with a pointer to the pending-nameservers article.dns/zone-setups/partial-setup/setup.mdx— adds a note in the TXT-verification step for partial (CNAME) setups, since the same article covers the partial branch too.dns/faq.mdx— the existing "Where can I find my Cloudflare nameservers?" answer now links to the pending-nameservers article for parent-zone verification instead of duplicating dig examples.Files changed
src/content/docs/dns/zone-setups/troubleshooting/pending-nameservers.mdx(rewritten)src/content/docs/dns/zone-setups/full-setup/troubleshooting.mdxsrc/content/docs/dns/zone-setups/full-setup/setup.mdxsrc/content/docs/dns/zone-setups/partial-setup/setup.mdxsrc/content/docs/dns/faq.mdx5 files changed, 137 insertions(+), 33 deletions(-).
DEE-3724