Add Spectrum troubleshooting docs for top support case drivers

src/content/docs/dns/manage-dns-records/troubleshooting/records-with-same-name.mdx

@@ -36,6 +36,12 @@ Review your existing DNS records to find the matching value in the **Name** fiel
 CNAME records are the only IP resolution record with this type of limitation. You can have more than one A/AAAA record per hostname, which is a way some domains do [simple load balancing](/dns/manage-dns-records/how-to/round-robin-dns/) for incoming requests.
 
 
+:::
+
+:::note[Spectrum applications]
+
+This DNS record conflict also applies when creating a [Spectrum](/spectrum/) application for a hostname that already has a proxied A, AAAA, or CNAME record. Cloudflare does not support having both a proxied DNS record (for HTTP/HTTPS traffic) and a Spectrum application on the same hostname, even on different ports. Refer to [Spectrum Limitations](/spectrum/reference/limitations/#using-the-same-hostname-for-http-proxy-and-spectrum) for details and recommended workarounds.
+
 :::
 
 [^1]: <Render file="cname-definition" />

src/content/docs/load-balancing/additional-options/spectrum.mdx

@@ -47,6 +47,9 @@ The exact settings will vary depending on your use case. Refer to the following
 7. On the **Monitors** page, define the settings presented and select **Next**.
    * Review the monitors attached to your pools.
    * If needed, you can attach an existing monitor or [create a new monitor](/load-balancing/monitors/create-monitor/#create-a-monitor).
+      :::caution[IP Access Rules and health checks]
+      If your Spectrum application has [IP Access Rules](/spectrum/reference/configuration-options/#ip-access-rules) enabled, Cloudflare's health check probes must be allowed by your rules. Otherwise, health checks will be blocked and all endpoints will be marked as unhealthy. To resolve this, add [Cloudflare IP addresses](https://www.cloudflare.com/ips/) to your IP Access Rules allowlist. Refer to [Spectrum Troubleshooting](/spectrum/reference/troubleshooting/#health-checks-fail-when-ip-access-rules-are-enabled) for details.
+      :::
 
 8. On the **Traffic Steering** page, choose an option for [Traffic steering](/load-balancing/understand-basics/traffic-steering/steering-policies/) and select **Next**.
 

src/content/docs/network/ip-geolocation.mdx

@@ -44,4 +44,6 @@ In order to use this data, you will need to then retrieve it from the [`CF-IPCou
 
 ## Report an incorrect IP location
 
-If you find an incorrect IP location that is part of the [current Cloudflare IP ranges](https://www.cloudflare.com/ips/), report to `ip-corrections@cloudflare.com`.
+If you find an IP address with a location that you believe is incorrect, fill in the [data correction form](https://www.cloudflare.com/lp/ip-corrections/) with the relevant IP address range(s) along with the correct information as applicable (country, state/province, city name, and ZIP code).
+
+If the data is confirmed, Cloudflare will make the necessary changes, which should be reflected within 48 hours.

src/content/docs/spectrum/reference/configuration-options.mdx

@@ -5,7 +5,11 @@ weight: 0
 
 ---
 
-Spectrum is a global TCP and UDP proxy running on Cloudflare's edge nodes. It does not terminate the connection. Instead it passes through the packets to the backend server.
+Spectrum is a global TCP and UDP proxy running on Cloudflare's edge nodes. It does not terminate the connection in the application-layer sense. However, at Layer 4, Spectrum does terminate the TCP and UDP sockets in both directions. The L4 payloads of TCP segments and UDP datagrams are passed back and forth as-is, without modifications.
+
+This means Spectrum does not inspect, modify, or upgrade application-layer protocols. For example, Spectrum cannot convert an HTTP connection to HTTPS, add HTTP headers, or apply WAF rules to TCP traffic. To add Layer 7 functionality such as CDN, Workers, or Bot Management, set the [application type](#application-type) to **HTTP/HTTPS**.
+
+For common issues and troubleshooting guidance, refer to [Spectrum Troubleshooting](/spectrum/reference/troubleshooting/).
 
 :::note
 
@@ -92,12 +96,26 @@ If IP Access rules are enabled for a Spectrum application, Cloudflare will respe
 Network analytics data for Spectrum does not reflect the outcomes of IP Access rules. Instead, to verify whether traffic was allowed or blocked based on these rules, consult the Spectrum event logs.
 :::
 
+:::caution[Health checks and IP Access Rules]
+When IP Access Rules are enabled with an allowlist model (allow specific IPs, block all others), Cloudflare Load Balancer health check probes may be blocked, causing all endpoints to appear unhealthy. To prevent this, add [Cloudflare IP addresses](https://www.cloudflare.com/ips/) to your allowlist. Refer to [Spectrum Troubleshooting](/spectrum/reference/troubleshooting/#health-checks-fail-when-ip-access-rules-are-enabled) for details.
+:::
+
+:::note
+[Custom rules](/waf/custom-rules/) (WAF rules) do not apply to Spectrum applications configured with the TCP/UDP application type. IP Access Rules are the only supported IP-based filtering mechanism for these applications. Refer to [Spectrum Limitations](/spectrum/reference/limitations/#ip-access-control) for details.
+:::
+
 ## Argo Smart Routing
 
 Once Argo Smart Routing is enabled for your application, traffic will automatically be routed through the fastest and most reliable network path available. Argo Smart Routing is available for TCP and UDP (beta) applications.
 
 ## Edge TLS Termination
 
+:::caution[Spectrum does not perform protocol upgrade]
+Spectrum operates at Layer 4 and forwards TCP payloads as-is. If Edge TLS Termination is set to **off** (Passthrough), Spectrum will **not** upgrade an HTTP connection to HTTPS, even if your origin listens on port 443. To encrypt traffic between Cloudflare and your origin, enable Edge TLS Termination and set it to **Full** or **Full (Strict)**.
+
+For example, if a client connects to your Spectrum application on port 8012 using HTTP, and your origin is configured on port 443, the connection to origin will use HTTP on port 443 — not HTTPS — unless Edge TLS Termination is enabled.
+:::
+
 If you enable **Edge TLS Termination** for a Spectrum application, Cloudflare will encrypt traffic for the application at the Edge. The Edge TLS Termination toggle applies only to TCP applications.
 
 Spectrum offers three modes of TLS termination: 'Flexible', 'Full', and 'Full (Strict)'.
@@ -118,6 +136,11 @@ If you have the TLS termination setting configured to **off**, this means that S
 
 :::caution
 
+Do not configure a TCP-type Spectrum application's origin to point to another Cloudflare-proxied hostname (for example, `origin.example.com.cdn.cloudflare.net`). This creates an unsupported double-proxy path that may result in TLS handshake failures (error 525). Use a direct origin IP address or a DNS hostname that resolves to your origin server without passing through Cloudflare's proxy. Refer to [Spectrum Troubleshooting](/spectrum/reference/troubleshooting/#error-525-ssl-handshake-failed) for details.
+:::
+
+:::caution
+
 If you need to control TLS settings, like the minimum TLS version or cipher suites, you need to use an HTTPS application.
 For TCP applications, default settings will apply. The minimum TLS version will be 1.1 and the cipher suites are:
 

src/content/docs/spectrum/reference/limitations.mdx

@@ -27,6 +27,42 @@ Minecraft Java Edition is supported but Minecraft Bedrock Edition is not support
 
 When using [Spectrum](/load-balancing/private-network/#on-ramps) as an on-ramp and [Magic WAN](/load-balancing/private-network/#magic-wan) as an off-ramp the [proxy protocol](/spectrum/how-to/enable-proxy-protocol/) setting in Spectrum is not supported.
 
+## IP access control
+
+Currently, [custom rules](/waf/custom-rules/) do not work with Spectrum applications. Use [IP Access rules](/waf/tools/ip-access-rules/) to allowlist, block, and challenge traffic for Spectrum applications based on the request's IP address, Autonomous System Number (ASN), or country.
+
+Refer to [Configuration options](/spectrum/reference/configuration-options/#ip-access-rules) for more information.
+
+## Using the same hostname for HTTP proxy and Spectrum
+
+You cannot configure both a [proxied DNS record](/dns/proxy-status/) (for HTTP/HTTPS traffic through the CDN and WAF) and a Spectrum application on the same hostname, even if they use different ports.
+
+When you attempt to create a Spectrum application for a hostname that already has a proxied A, AAAA, or CNAME record, the dashboard returns:
+
+> **"An A, AAAA or CNAME record already exists with that host."**
+
+This is a platform limitation, not a dashboard-only restriction. The same error occurs when using the API.
+
+### Why this happens
+
+Spectrum applications provision their own DNS records to map a hostname to Spectrum's edge IPs. A proxied DNS record maps the same hostname to Cloudflare's CDN edge IPs. These two IP assignments conflict because a single hostname cannot simultaneously resolve to both Spectrum edge IPs and CDN edge IPs.
+
+### Recommended architecture
+
+Use separate hostnames for HTTP/HTTPS traffic (protected by WAF) and TCP/UDP traffic (proxied by Spectrum):
+
+| Traffic type | Example hostname | Cloudflare service |
+|---|---|---|
+| HTTPS (web UI, APIs, authentication) | `app.example.com` | Proxied DNS record with CDN/WAF |
+| TCP/UDP (custom protocols, ICA, SSH) | `app-tcp.example.com` | Spectrum application |
+
+Configure your application or client software to use the appropriate hostname for each traffic type. For example, in a Citrix Gateway deployment:
+- `citrix.example.com` on port 443 for the web UI and authentication (WAF-protected).
+- `citrix-ica.example.com` on port 4443 for ICA/HDX session traffic (Spectrum).
+- Configure Citrix StoreFront to generate ICA files pointing to `citrix-ica.example.com:4443`.
+
+For additional troubleshooting, refer to [Spectrum Troubleshooting](/spectrum/reference/troubleshooting/#cannot-create-spectrum-application--dns-record-already-exists).
+
 ## Listen on ports configuration
 
 By default, Spectrum is configured to listen on all ports, which can raise concerns for security auditors. However, it is important to note that Spectrum will only proxy connections from edge ports that are specifically configured within Cloudflare.

src/content/docs/spectrum/reference/logs.mdx

@@ -15,7 +15,9 @@ Spectrum [log events](/logs/logpush/logpush-job/datasets/) can be configured thr
 
 ## Status Codes
 
-
+:::note[Spectrum status codes are not HTTP status codes]
+The status codes in the table below are Spectrum-specific connection status codes. They describe the outcome of Layer 4 (TCP/UDP) connections, not HTTP transactions. Some codes share numbers with HTTP status codes (for example, 444, 499) but have different meanings in the Spectrum context. For guidance on interpreting common status code patterns, refer to [Spectrum Troubleshooting](/spectrum/reference/troubleshooting/#understanding-common-spectrum-event-log-status-codes).
+:::
 
 | Code | Description                                                                                        |
 | ---- | -------------------------------------------------------------------------------------------------- |

src/content/docs/spectrum/reference/troubleshooting.mdx

@@ -0,0 +1,143 @@
+---
+pcx_content_type: troubleshooting
+title: Troubleshooting
+weight: 0
+tags:
+  - Debugging
+
+---
+
+This page covers common issues when configuring and operating Spectrum applications. For Spectrum event log status codes, refer to [Event logs](/spectrum/reference/logs/).
+
+## Health checks fail when IP Access Rules are enabled
+
+### Symptoms
+
+- Cloudflare Load Balancer health checks report all endpoints as unhealthy with the error `Connection reset by peer`.
+- Removing IP Access Rules from the Spectrum application causes health checks to succeed.
+- The Spectrum application itself works correctly for client traffic that is allowed by the IP Access Rules.
+
+### Cause
+
+When you enable [IP Access Rules](/spectrum/reference/configuration-options/#ip-access-rules) on a Spectrum application, all incoming connections are evaluated against your rules — including connections from Cloudflare's own health check probes. If your IP Access Rules use an allowlist model (allow specific IPs, block everything else), Cloudflare's health check source IPs will be blocked, causing health checks to fail.
+
+### Solution
+
+Add Cloudflare's IP ranges to your IP Access Rules allowlist. You can find the current list of Cloudflare IP addresses at [cloudflare.com/ips](https://www.cloudflare.com/ips/).
+
+Alternatively, if you only need to restrict client access (not health check access), consider configuring health checks to use a TCP check type that validates the connection can be established, and manage your access control at the origin level instead.
+
+:::note
+
+[Custom rules](/waf/custom-rules/) (WAF rules) do not apply to Spectrum applications configured with the TCP/UDP application type. For Spectrum, IP Access Rules are the only supported mechanism for IP-based filtering. Refer to [Spectrum Limitations](/spectrum/reference/limitations/#ip-access-control).
+
+:::
+
+---
+
+## Cannot create Spectrum application — DNS record already exists
+
+### Symptoms
+
+- When creating a Spectrum application in the dashboard, you receive the error: **"An A, AAAA or CNAME record already exists with that host."**
+- You are trying to use the same hostname for both an HTTP-proxied service (through Cloudflare's CDN/WAF) and a Spectrum TCP or UDP application on a different port.
+
+### Cause
+
+Cloudflare does not support having both a proxied DNS record (used for HTTP/HTTPS traffic through the CDN and WAF) and a Spectrum application on the same hostname. This is a platform limitation, not a dashboard-only restriction.
+
+When a Spectrum application is created, it provisions its own DNS record for the hostname. This conflicts with any existing proxied A, AAAA, or CNAME record for that same hostname.
+
+### Solution
+
+Use a **split-hostname architecture** where HTTP/HTTPS traffic and TCP/UDP traffic use different hostnames:
+
+| Traffic type | Hostname | Cloudflare service |
+|---|---|---|
+| HTTPS (web UI, APIs) | `app.example.com` | Proxied DNS record with CDN/WAF |
+| TCP (custom protocol, ICA/HDX, etc.) | `app-tcp.example.com` | Spectrum application |
+
+Configure your application or client to use the appropriate hostname for each traffic type.
+
+:::note[Common use case: Citrix Gateway / VDI]
+
+A common scenario where this limitation is encountered is Citrix Gateway deployments, where the web UI and authentication flow use HTTPS (requiring WAF protection) while ICA/HDX session traffic uses TCP on a different port. In this case, configure the Citrix StoreFront to generate ICA files pointing to the Spectrum hostname (for example, `citrix-ica.example.com:4443`) while keeping the web UI on the WAF-protected hostname (`citrix.example.com:443`).
+
+:::
+
+For more details on this limitation, refer to [Spectrum Limitations — Using the same hostname for HTTP proxy and Spectrum](/spectrum/reference/limitations/#using-the-same-hostname-for-http-proxy-and-spectrum).
+
+---
+
+## Origin receives HTTP instead of HTTPS (protocol mismatch)
+
+### Symptoms
+
+- Your Spectrum application edge port uses HTTP (for example, port 8012), and your origin expects HTTPS on port 443.
+- The origin rejects the connection or returns errors because it receives plaintext HTTP instead of encrypted HTTPS.
+- The configuration appears to work as: `http:8012 → Cloudflare Spectrum → http:443 (origin)` instead of the expected `http:8012 → Cloudflare Spectrum → https:443 (origin)`.
+
+### Cause
+
+Spectrum operates at Layer 4 (TCP/UDP). When Edge TLS Termination is set to **off** (Passthrough), Spectrum forwards the raw TCP payload to the origin without modification. It does not perform protocol upgrade — connecting to an origin on port 443 does not automatically mean the connection will use HTTPS.
+
+### Solution
+
+To send encrypted traffic from Cloudflare to your origin, you must enable **Edge TLS Termination** on the Spectrum application and set it to **Full** or **Full (Strict)**:
+
+- **Full**: Cloudflare connects to origin using TLS but does not validate the origin certificate.
+- **Full (Strict)**: Cloudflare connects to origin using TLS and validates the origin certificate against a trusted CA or Cloudflare Origin CA.
+
+You can configure Edge TLS Termination in the Spectrum application settings in the dashboard, or via the API by setting the `tls` field to `full` or `strict`.
+
+Refer to [Edge TLS Termination](/spectrum/reference/configuration-options/#edge-tls-termination) for more details.
+
+---
+
+## Error 525: SSL handshake failed
+
+### Symptoms
+
+- Clients connecting through Spectrum receive HTTP 525 errors.
+- The error occurs after enabling a Spectrum application or changing TLS settings.
+
+### Cause
+
+Error 525 indicates that the TLS handshake between Cloudflare and your origin server failed. In a Spectrum context, common causes include:
+
+1. **Edge TLS Termination is set to Full or Full (Strict)**, but the origin does not have a valid TLS certificate or does not accept TLS connections on the configured port.
+2. **The Spectrum application origin points to another Cloudflare-proxied hostname** (for example, `origin.example.com.cdn.cloudflare.net`). This creates a double-proxy chain that is not supported for TCP application types and can cause TLS handshake failures.
+3. **TLS version or cipher mismatch** between Cloudflare's edge and the origin server.
+
+### Solution
+
+- Verify that your origin server has a valid TLS certificate and is configured to accept TLS connections on the origin port.
+- If using **Full (Strict)**, ensure the origin certificate is issued by a publicly trusted CA or a [Cloudflare Origin CA certificate](/ssl/origin-configuration/origin-ca/).
+- Do not route a TCP-type Spectrum application through another Cloudflare-proxied hostname. Use a direct origin IP address or a DNS name that resolves directly to your origin server (not through Cloudflare's proxy).
+- If the origin only supports specific TLS versions, note that Spectrum supports TLS 1.1, 1.2, and 1.3 when Edge TLS Termination is enabled.
+
+---
+
+## Understanding common Spectrum event log status codes
+
+Spectrum uses its own set of connection status codes that are distinct from HTTP status codes used by Cloudflare's CDN layer. Some codes share numbers (for example, 444, 499) but have different meanings.
+
+For the full status code table, refer to [Event logs](/spectrum/reference/logs/).
+
+### Common patterns
+
+| Pattern | Likely cause | Recommended action |
+|---|---|---|
+| High volume of **444** (Origin sent RST) | Origin server is actively resetting connections. May indicate origin overload, misconfigured firewall, or application crash. | Check origin server health, firewall rules, and application logs. |
+| High volume of **445** (Origin timeout) | Established connections to origin are timing out. May indicate origin is slow to respond or network path issues. | Check origin server performance and network connectivity between Cloudflare and origin. |
+| High volume of **497** (Client timeout) | Client connections are timing out. May indicate network issues between clients and Cloudflare edge, or clients with very long idle connections. | Review client network conditions and consider adjusting idle timeout expectations. |
+| High volume of **498** (Client broken pipe) | Client connections are dropping mid-session. May indicate unstable client networks (for example, mobile users). | Often expected for mobile or unreliable networks. Monitor for trends. |
+| High volume of **499** (Client sent RST) | Clients are actively closing connections. May indicate client-side timeouts or application-level disconnects. | Review client application timeout settings. |
+| **521** (Origin refused connection) | Origin is not accepting connections on the configured port. | Verify origin server is running and listening on the correct port. Check origin firewall. |
+| **522** (Origin connection timeout) | Cannot establish a TCP connection to origin. | Verify origin IP address, port, and that origin is reachable from Cloudflare. |
+
+:::note
+
+Network Analytics data for Spectrum does not reflect the outcomes of IP Access Rules. To verify whether traffic was allowed or blocked based on IP Access Rules, consult the Spectrum event logs.
+
+:::