Cloudflare Deploy | Package file

Version 49f948fa.bb1 · Apache-2.0. This preview displays packaged text and does not execute code. Treat the contents as untrusted instructions.

Common Issues

Connection Timeouts

Problem: Connections fail or timeout
Cause: Origin firewall blocking Cloudflare IPs, origin service not running, incorrect DNS
Solution: 1. Verify origin firewall allows Cloudflare IP ranges 2. Check origin service running on correct port 3. Ensure DNS record is CNAME (not A/AAAA) 4. Verify origin IP/hostname is correct

# Test connectivity
nc -zv app.example.com 22
dig app.example.com

Client IP Showing Cloudflare IP

Problem: Origin logs show Cloudflare IPs not real client IPs
Cause: Proxy Protocol not enabled or origin not configured
Solution:

// Enable in Spectrum app
const app = await client.spectrum.apps.create({
  // ...
  proxy_protocol: 'v1',  // TCP: v1/v2; UDP: simple
});

Origin config: - nginx: listen 22 proxy_protocol; - HAProxy: bind :22 accept-proxy

TLS Errors

Problem: TLS handshake failures, 525 errors
Cause: TLS mode mismatch

Error	TLS Mode	Problem	Solution
Connection refused	`full`/`strict`	Origin not TLS	Use `tls: "off"` or enable TLS
525 cert invalid	`strict`	Self-signed cert	Use `tls: "full"` or valid cert
Handshake timeout	`flexible`	Origin expects TLS	Use `tls: "full"`

Debug:

openssl s_client -connect app.example.com:443 -showcerts

SMTP Reverse DNS

Problem: Email servers reject SMTP via Spectrum
Cause: Spectrum IPs lack PTR (reverse DNS) records
Impact: Many mail servers require valid rDNS for anti-spam

Solution: - Outbound SMTP: NOT recommended through Spectrum - Inbound SMTP: Use Cloudflare Email Routing - Internal relay: Whitelist Spectrum IPs on destination

Proxy Protocol Compatibility

Problem: Connection works but app behaves incorrectly
Cause: Origin doesn't support Proxy Protocol

Solution: 1. Verify origin supports version (v1: widely supported, v2: HAProxy 1.5+/nginx 1.11+) 2. Test with proxy_protocol: 'off' first 3. Configure origin to parse headers

nginx TCP:

stream {
    server {
        listen 22 proxy_protocol;
        proxy_pass backend:22;
    }
}

HAProxy:

frontend ft_ssh
    bind :22 accept-proxy

Analytics Data Retention

Problem: Historical data not available
Cause: Retention varies by plan

Plan	Real-time	Historical
Pro	Last hour	❌
Business	Last hour	Limited
Enterprise	Last hour	90+ days

Solution: Query within retention window or export to external system

Enterprise-Only Features

Problem: Feature unavailable/errors
Cause: Requires Enterprise plan

Enterprise-only: - Port ranges (tcp/25565-25575) - All TCP/UDP ports (Pro/Business: selected only) - Extended analytics retention - Advanced load balancing

IPv6 Considerations

Problem: IPv6 clients can't connect or origin doesn't support IPv6
Solution: Configure edge_ips.connectivity

const app = await client.spectrum.apps.create({
  // ...
  edge_ips: {
    type: 'dynamic',
    connectivity: 'ipv4',  // Options: 'all', 'ipv4', 'ipv6'
  },
});

Options: - all: Dual-stack (default, requires origin support both) - ipv4: IPv4 only (use if origin lacks IPv6) - ipv6: IPv6 only (rare)

Limits

Resource	Pro/Business	Enterprise
Max apps	~10-15	100+
Protocols	Selected	All TCP/UDP
Port ranges	❌	✅
Analytics	~1 hour	90+ days

openai-cloudflare-deploy/references/spectrum/gotchas.md