Add Spectrum troubleshooting docs for top support case drivers

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

@@ -23,6 +23,7 @@ You will encounter this error if you try to do one of the following:
 
 - Create a CNAME record with a **Name** matching the name of an existing A/AAAA[^2] or CNAME record.
 - Create an A/AAAA record with a **Name** matching the name of an existing CNAME record.
+- Create a [Spectrum](/spectrum/) application for a name that already has a manually-created `A`, `AAAA`, or `CNAME` record. Spectrum provisions and manages its own DNS record for the application, so Cloudflare does not support having both on the same name. Multiple Spectrum applications can, however, share the same name. Refer to [Spectrum Troubleshooting](/spectrum/reference/troubleshooting/#cannot-create-spectrum-application--dns-record-already-exists) for recommended workarounds.
 
 Cloudflare prevents you from creating this combination of records because if a CNAME record is provided for a hostname DNS servers expect only that CNAME record to provide DNS information for that hostname.
 

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

@@ -9,6 +9,10 @@ weight: 0
 
 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
 Some of these features require an Enterprise plan. If you would like to upgrade, contact your account team.
 :::
@@ -115,6 +119,12 @@ Spectrum virtual network origins are for TCP and UDP traffic only. For HTTP/HTTP
 
 ## 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 set to **Full** or **Full (Strict)**.
+:::
+
 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)'.
@@ -135,6 +145,12 @@ 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 at the origin. For TCP applications, a failed TLS handshake to the origin is reported as an origin connection failure (`521` or `522`), not error `525` — `525` applies to HTTP/HTTPS applications. 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/#tls-handshake-failures-error-525) 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:
 
@@ -185,4 +201,4 @@ The cipher suites below are ordered based on how they appear in the ClientHello,
 | AES128-SHA                        | ✅      | ✅      | ❌      |
 | AES256-SHA                        | ✅      | ✅      | ❌      |
 
-[^1]: Although TLS 1.3 uses the same cipher suite space as previous versions of TLS, TLS 1.3 cipher suites are defined differently, only specifying the symmetric ciphers, and cannot be used for TLS 1.2. Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 1.3 ([RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html)). BoringSSL also hard-codes cipher preferences in this order for TLS 1.3. Refer to [TLS 1.3 cipher suites](/ssl/origin-configuration/cipher-suites/#tls-13-cipher-suites) for details.
+[^1]: Although TLS 1.3 uses the same cipher suite space as previous versions of TLS, TLS 1.3 cipher suites are defined differently, only specifying the symmetric ciphers, and cannot be used with TLS 1.2. Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 1.3 ([RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html)). BoringSSL also hard-codes cipher preferences in this order for TLS 1.3. Refer to [TLS 1.3 cipher suites](/ssl/origin-configuration/cipher-suites/#tls-13-cipher-suites) for details.

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

@@ -19,7 +19,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 Spectrum status code table 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/#common-spectrum-event-log-status-codes).
+:::
 
 | Code | Description                                                                                        |
 | ---- | -------------------------------------------------------------------------------------------------- |

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

@@ -27,3 +27,110 @@ When a Spectrum application uses a [virtual network origin](/spectrum/reference/
 ### Cloudflare WAN as the connector
 
 For tunnel health, BGP, and routing diagnostics on WAN-connected origins, refer to [Troubleshoot Cloudflare WAN](/cloudflare-wan/troubleshooting/).
+
+## 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 already have a manually-created proxied DNS record (`A`, `AAAA`, or `CNAME`) for the hostname you are trying to use for a new Spectrum application.
+
+### Cause
+
+Cloudflare does not support having both a manually-created proxied DNS record (`A`, `AAAA`, or `CNAME`) and a Spectrum application on the same hostname. This is because Spectrum provisions and manages its own DNS record for the application, which conflicts with the existing manually-created record. This is a platform limitation, not a dashboard-only restriction.
+
+This limitation only applies to manually-created proxied records. Multiple Spectrum applications — including a mix of HTTP/HTTPS and TCP/UDP application types — can share the same hostname, because Spectrum manages the DNS record for each of them.
+
+### Solution
+
+If you only need Spectrum applications on the hostname (for example, an HTTP/HTTPS Spectrum application alongside a TCP/UDP Spectrum application), you do not need a workaround — create the additional Spectrum application on the same hostname.
+
+If you need to keep a manually-created proxied DNS record on the hostname (for example, to route standard HTTP/HTTPS traffic through the CDN and WAF instead of through Spectrum), use a **split-hostname architecture** instead, where the manually-created proxied record and the Spectrum application use different hostnames:
+
+| Traffic type | Hostname | Cloudflare service |
+|---|---|---|
+| HTTPS (web UI, APIs) | `app.example.com` | Manually-created proxied DNS record with CDN/WAF |
+| TCP (custom protocol, ICA/HDX, and similar) | `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 through a manually-created proxied record (requiring WAF protection) while ICA/HDX session traffic uses TCP on a different port through a Spectrum application. 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](/spectrum/reference/limitations/).
+
+## 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 turn on **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.
+
+## TLS handshake failures (error 525)
+
+### Symptoms
+
+- For TCP applications with Edge TLS Termination set to **Full** or **Full (Strict)**: connections to the origin fail. Spectrum event logs may show `521` (connection refused) or `522` (connection timeout) because a failed TLS handshake at the origin is reported as an origin connection failure. Refer to [Event logs](/spectrum/reference/logs/) for the full status code reference.
+- For HTTP/HTTPS applications: clients receive error `525` (SSL handshake failed).
+
+These errors typically appear after creating a Spectrum application or modifying TLS settings.
+
+### Cause
+
+The TLS handshake between Cloudflare and your origin server failed. Common causes include:
+
+- **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.
+- **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.
+- **TLS version or cipher mismatch** between Cloudflare's edge and the origin server.
+
+### Solution
+
+1. Verify that your origin server has a valid TLS certificate and is configured to accept TLS connections on the origin port.
+2. 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/).
+3. Confirm that the Spectrum application origin is not pointing to 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).
+4. 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 turned on.
+
+## 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
+
+The following table lists frequently observed Spectrum status code patterns and their likely causes:
+
+| 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.
+
+:::