references/spectrum/gotchas.md

## 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

```bash
# 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:**
```typescript
// 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:**
```bash
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:**
```nginx
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`

```typescript
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 |

## See Also

- [patterns.md](patterns.md) - Protocol examples
- [configuration.md](configuration.md) - TLS/Proxy setup