1## Common Issues
2 
3### Connection Timeouts
4 
5**Problem:** Connections fail or timeout  
6**Cause:** Origin firewall blocking Cloudflare IPs, origin service not running, incorrect DNS  
7**Solution:**
81. Verify origin firewall allows Cloudflare IP ranges
92. Check origin service running on correct port
103. Ensure DNS record is CNAME (not A/AAAA)
114. Verify origin IP/hostname is correct
12 
13```bash
14# Test connectivity
15nc -zv app.example.com 22
16dig app.example.com
17```
18 
19### Client IP Showing Cloudflare IP
20 
21**Problem:** Origin logs show Cloudflare IPs not real client IPs  
22**Cause:** Proxy Protocol not enabled or origin not configured  
23**Solution:**
24```typescript
25// Enable in Spectrum app
26const app = await client.spectrum.apps.create({
27  // ...
28  proxy_protocol: 'v1',  // TCP: v1/v2; UDP: simple
29});
30```
31 
32**Origin config:**
33- **nginx**: `listen 22 proxy_protocol;`
34- **HAProxy**: `bind :22 accept-proxy`
35 
36### TLS Errors
37 
38**Problem:** TLS handshake failures, 525 errors  
39**Cause:** TLS mode mismatch
40 
41| Error | TLS Mode | Problem | Solution |
42|-------|----------|---------|----------|
43| Connection refused | `full`/`strict` | Origin not TLS | Use `tls: "off"` or enable TLS |
44| 525 cert invalid | `strict` | Self-signed cert | Use `tls: "full"` or valid cert |
45| Handshake timeout | `flexible` | Origin expects TLS | Use `tls: "full"` |
46 
47**Debug:**
48```bash
49openssl s_client -connect app.example.com:443 -showcerts
50```
51 
52### SMTP Reverse DNS
53 
54**Problem:** Email servers reject SMTP via Spectrum  
55**Cause:** Spectrum IPs lack PTR (reverse DNS) records  
56**Impact:** Many mail servers require valid rDNS for anti-spam
57 
58**Solution:**
59- Outbound SMTP: NOT recommended through Spectrum
60- Inbound SMTP: Use Cloudflare Email Routing
61- Internal relay: Whitelist Spectrum IPs on destination
62 
63### Proxy Protocol Compatibility
64 
65**Problem:** Connection works but app behaves incorrectly  
66**Cause:** Origin doesn't support Proxy Protocol
67 
68**Solution:**
691. Verify origin supports version (v1: widely supported, v2: HAProxy 1.5+/nginx 1.11+)
702. Test with `proxy_protocol: 'off'` first
713. Configure origin to parse headers
72 
73**nginx TCP:**
74```nginx
75stream {
76    server {
77        listen 22 proxy_protocol;
78        proxy_pass backend:22;
79    }
80}
81```
82 
83**HAProxy:**
84```
85frontend ft_ssh
86    bind :22 accept-proxy
87```
88 
89### Analytics Data Retention
90 
91**Problem:** Historical data not available  
92**Cause:** Retention varies by plan
93 
94| Plan | Real-time | Historical |
95|------|-----------|------------|
96| Pro | Last hour | ❌ |
97| Business | Last hour | Limited |
98| Enterprise | Last hour | 90+ days |
99 
100**Solution:** Query within retention window or export to external system
101 
102### Enterprise-Only Features
103 
104**Problem:** Feature unavailable/errors  
105**Cause:** Requires Enterprise plan
106 
107**Enterprise-only:**
108- Port ranges (`tcp/25565-25575`)
109- All TCP/UDP ports (Pro/Business: selected only)
110- Extended analytics retention
111- Advanced load balancing
112 
113### IPv6 Considerations
114 
115**Problem:** IPv6 clients can't connect or origin doesn't support IPv6  
116**Solution:** Configure `edge_ips.connectivity`
117 
118```typescript
119const app = await client.spectrum.apps.create({
120  // ...
121  edge_ips: {
122    type: 'dynamic',
123    connectivity: 'ipv4',  // Options: 'all', 'ipv4', 'ipv6'
124  },
125});
126```
127 
128**Options:**
129- `all`: Dual-stack (default, requires origin support both)
130- `ipv4`: IPv4 only (use if origin lacks IPv6)
131- `ipv6`: IPv6 only (rare)
132 
133## Limits
134 
135| Resource | Pro/Business | Enterprise |
136|----------|--------------|------------|
137| Max apps | ~10-15 | 100+ |
138| Protocols | Selected | All TCP/UDP |
139| Port ranges | ❌ | ✅ |
140| Analytics | ~1 hour | 90+ days |
141 
142## See Also
143 
144- [patterns.md](patterns.md) - Protocol examples
145- [configuration.md](configuration.md) - TLS/Proxy setup
146