Skip to content

Add Spectrum troubleshooting docs for top support case drivers#30683

Open
stechedo wants to merge 1 commit into
cloudflare:productionfrom
stechedo:spectrum-troubleshooting-docs
Open

Add Spectrum troubleshooting docs for top support case drivers#30683
stechedo wants to merge 1 commit into
cloudflare:productionfrom
stechedo:spectrum-troubleshooting-docs

Conversation

@stechedo

@stechedo stechedo commented May 7, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds a new Spectrum Troubleshooting page and improves existing Spectrum documentation to address the top 3 case-generating issues identified in the April 2026 Network Support-by-Request (SBR) case review (~190 cases analyzed).

Estimated case deflection: 9-13 cases/month across these 3 issues.

Changes

New page

  • /spectrum/reference/troubleshooting/ — New troubleshooting page with structured symptom/cause/solution sections covering:
    • Health checks failing when IP Access Rules are enabled
    • DNS record conflict when creating Spectrum apps (same hostname as proxied record)
    • Protocol mismatch (origin receives HTTP instead of HTTPS)
    • Error 525 (SSL handshake failed) in Spectrum context
    • Common Spectrum event log status code patterns (444, 445, 497-499, 521, 522)

Modified pages (5)

  • /spectrum/reference/configuration-options/ — Added warnings about IP Access Rules blocking health checks, Custom Rules not working with Spectrum, protocol upgrade not being supported, and double-proxy chains causing 525 errors. Expanded intro paragraph to clarify Spectrum's L4 pass-through behavior.
  • /spectrum/reference/limitations/ — Added new "IP access control" section and "Using the same hostname for HTTP proxy and Spectrum" section documenting the platform limitation and recommending split-hostname architecture (with Citrix Gateway use case).
  • /spectrum/reference/logs/ — Added note clarifying that Spectrum status codes are distinct from HTTP status codes, with cross-link to troubleshooting page.
  • /load-balancing/additional-options/spectrum/ — Added caution callout in the Monitors setup step warning about IP Access Rules blocking health checks.
  • /dns/manage-dns-records/troubleshooting/records-with-same-name/ — Added note explaining that DNS record conflicts also apply to Spectrum applications, with cross-link to Spectrum limitations.

Motivation

These documentation gaps were identified by reviewing all April 2026 Network SBR cases. The top case-generating patterns were:

  1. IP Access Rules + Healthchecks (~3-5 cases/month): Customers enable IP Access Rules, health checks fail silently. No docs explain the interaction.
  2. Same Hostname WAF + Spectrum (~3-4 cases/month): Customers hit "DNS record already exists" error with no explanation that it's a hard platform limitation. Common in Citrix/VDI deployments.
  3. Protocol Mismatch / TLS errors (~3-4 cases/month): Customers expect Spectrum to upgrade HTTP→HTTPS or chain through another Cloudflare proxy. Neither is supported but neither was documented.

Content area

Spectrum, Load Balancing, DNS

@stechedo stechedo requested a review from dcpena as a code owner May 7, 2026 16:58
@stechedo stechedo requested a review from a team May 7, 2026 16:58
@stechedo stechedo requested a review from RebeccaTamachiro as a code owner May 7, 2026 16:58
@github-actions github-actions Bot added product:load-balancing Related to Load Balancing product product:spectrum Related to Spectrum product product:dns Issues or PRs related to DNS product:network size/m labels May 7, 2026
@github-actions

github-actions Bot commented May 27, 2026

Copy link
Copy Markdown
Contributor

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).

@github-actions github-actions Bot added the stale label May 27, 2026
@stechedo stechedo force-pushed the spectrum-troubleshooting-docs branch from 959bdcb to f311329 Compare June 26, 2026 19:04
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Jun 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review

Reviewing new changes (commit 4e5ee85)…

⚠️ 13 warnings, 💡 3 suggestions found in commit f311329.

Fan Out Code Review

This code review is in beta and may not always be helpful — use your judgment.

Warnings (2)
File Issue
spectrum/reference/limitations.mdx line 51 Duplicate section heading — The PR adds an ## IP access control section at line 51, but the same ## IP access control section already exists later in the file (after ## Listen on ports configuration), creating duplicate headings and repeated content on the page. Fix: Remove the duplicate. Either keep the newly added section and delete the older one near the bottom, or remove the new addition at line 51 if the intent was only to reorganize.
spectrum/reference/configuration-options.mdx line 133 TLS mode guidance oversimplified — The example states an HTTP client connection reaches the origin as HTTP 'unless Edge TLS Termination is enabled,' but the immediately preceding sentence correctly limits origin encryption to Full or Full (Strict) mode. Flexible mode terminates TLS at the edge yet still sends unencrypted traffic to the origin, so the example contradicts the more precise guidance and could mislead readers about which mode actually encrypts the Cloudflare-to-origin path. Fix: Change line 133 to say 'unless Edge TLS Termination is set to Full or Full (Strict)' so it matches the preceding guidance.

Style Guide Review

Warnings (11)
File Issue
spectrum/reference/troubleshooting.mdx line 45 Enable/disable for toggles — Line uses 'enable' for a toggle: 'When you enable [IP Access Rules]...' Fix: Use 'turn on' instead of 'enable' for toggles.
spectrum/reference/troubleshooting.mdx line 101 Enable/disable for toggles — Line uses 'enable' for a setting: 'you must enable **Edge TLS Termination**...' Fix: Use 'turn on' instead of 'enable' for toggles.
spectrum/reference/troubleshooting.mdx line 121 Numbered list for non-sequential items — Common causes are listed as 1/2/3, but causes are unordered items. Fix: Use bullet points instead of a numbered list for unordered causes.
spectrum/reference/troubleshooting.mdx line 127 Bulleted list for sequential steps — Solution steps are listed as bullets rather than a numbered procedure. Fix: Use a numbered list for sequential troubleshooting steps.
spectrum/reference/troubleshooting.mdx line 138 Table introduced with sentence fragment — The status-code table follows a heading with no introductory sentence ending in a colon. Fix: Introduce the table with a complete sentence ending in a colon.
spectrum/reference/troubleshooting.mdx line 132 Heading begins with -ing verb — Heading starts with a gerund: 'Understanding common Spectrum event log status codes'. Fix: Rewrite as a noun phrase, e.g. 'Common Spectrum event log status codes'.
spectrum/reference/limitations.mdx line 57 Headings should not begin with an -ing verb — Body heading starts with Using (## Using the same hostname for HTTP proxy and Spectrum). Fix: Rewrite in imperative form, e.g. ## Use separate hostnames for HTTP proxy and Spectrum.
spectrum/reference/limitations.mdx line 81 Port numbers should be monospaced — Line uses port 443 without backticks around the port number. Fix: Monospace the port number: port \443``.
spectrum/reference/limitations.mdx line 82 Port numbers should be monospaced — Line uses port 4443 without backticks around the port number. Fix: Monospace the port number: port \4443``.
dns/manage-dns-records/troubleshooting/records-with-same-name.mdx line 43 DNS record types must use monospace — Line adds A, AAAA, or CNAME record using plain text Fix: Use backticks: `A`, `AAAA`, or `CNAME` record
spectrum/reference/logs.mdx line 23 No directional words — Line uses "the table below" Fix: Replace with a direct reference, e.g., "the Spectrum status code table"
Suggestions (3)
File Issue
spectrum/reference/troubleshooting.mdx line 75 Avoid etc. — Table cell contains 'ICA/HDX, etc.' Fix: Replace 'etc.' with a complete list or 'and so on'.
spectrum/reference/troubleshooting.mdx line 114 Bullet list has fewer than three items — Two-item bullet list of symptoms. Fix: Consider writing the two symptoms as prose instead.
spectrum/reference/configuration-options.mdx line 160 Multiple same-type admonitions in the same section — Patch adds a second :::caution block in the same TLS termination subsection; the second block is empty. Fix: Remove the empty :::caution marker or merge the caution content into a single :::caution block.
Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command Description
/review Runs a review now. Incremental if a prior review exists, full if not.
/full-review Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/fan-out-review Forces a full review using the per-file fan-out mode regardless of diff size. Each file is reviewed in its own session for maximum per-file detail. ⚠️ This may take a very long time on large PRs and may fail or time out — use only when you want the most thorough review and are willing to wait.
/holistic-review Forces a full review using the holistic mode regardless of diff size. The entire diff is reviewed in one pass, enabling cross-file reasoning. Faster and more reliable on large PRs.
/ignore-review-limit Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.

@stechedo
Add Spectrum troubleshooting page and improve docs for top support ca…
4e5ee85 
…se drivers

Based on analysis of April 2026 Network SBR cases, add documentation
to address the top 3 case-generating Spectrum issues:

1. IP Access Rules + Health Checks interaction: Customers enable IP
   Access Rules on Spectrum apps, then Cloudflare health checks fail
   because probe IPs are blocked. Added warnings to configuration-options
   and load-balancing/spectrum pages.

2. Same hostname for WAF + Spectrum: Customers attempt to use the same
   hostname for HTTP (WAF) and TCP (Spectrum) on different ports. This
   is a platform limitation. Added new section to limitations page and
   cross-reference on DNS troubleshooting page.

3. Edge TLS / Protocol mismatch: Customers configure HTTP edge ports
   expecting HTTPS to origin. Spectrum does not upgrade protocols.
   Added warnings to Edge TLS Termination section.

Also:
- Created new /spectrum/reference/troubleshooting/ page with structured
  symptom/cause/solution sections for all three issues plus error 525
  and common status code patterns
- Added note to /spectrum/reference/logs/ clarifying that Spectrum
  status codes are distinct from HTTP status codes
@stechedo stechedo force-pushed the spectrum-troubleshooting-docs branch from f311329 to 4e5ee85 Compare June 26, 2026 19:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dcpena dcpena Awaiting requested review from dcpena
@RebeccaTamachiro RebeccaTamachiro Awaiting requested review from RebeccaTamachiro
@elithrar elithrar Awaiting requested review from elithrar elithrar is a code owner
@ncrouch-cflare ncrouch-cflare Awaiting requested review from ncrouch-cflare ncrouch-cflare is a code owner
@hannes-cf hannes-cf Awaiting requested review from hannes-cf hannes-cf is a code owner
@esomoza-cf esomoza-cf Awaiting requested review from esomoza-cf esomoza-cf is a code owner
@xofyarg xofyarg Awaiting requested review from xofyarg xofyarg is a code owner
@dklbreitling dklbreitling Awaiting requested review from dklbreitling dklbreitling is a code owner
@chreo chreo Awaiting requested review from chreo chreo is a code owner
@svenr-cf svenr-cf Awaiting requested review from svenr-cf svenr-cf is a code owner
@kerolasa kerolasa Awaiting requested review from kerolasa kerolasa is a code owner
@matildeopbravo matildeopbravo Awaiting requested review from matildeopbravo matildeopbravo is a code owner
@vendemiat vendemiat Awaiting requested review from vendemiat vendemiat is a code owner
@Woutifier Woutifier Awaiting requested review from Woutifier Woutifier is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@RebeccaTamachiro RebeccaTamachiro

@dcpena dcpena

Labels

product:dns Issues or PRs related to DNS product:load-balancing Related to Load Balancing product product:network product:spectrum Related to Spectrum product size/m stale

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@stechedo @RebeccaTamachiro @dcpena