1# Tunnel Gotchas
2 
3## Common Errors
4 
5### "Error 1016 (Origin DNS Error)"
6 
7**Cause:** Tunnel not running or not connected
8**Solution:**
9```bash
10cloudflared tunnel info my-tunnel     # Check status
11ps aux | grep cloudflared             # Verify running
12journalctl -u cloudflared -n 100      # Check logs
13```
14 
15### "Self-signed certificate rejected"
16 
17**Cause:** Origin using self-signed certificate
18**Solution:**
19```yaml
20originRequest:
21  noTLSVerify: true      # Dev only
22  caPool: /path/to/ca.pem  # Custom CA
23```
24 
25### "Connection timeout"
26 
27**Cause:** Origin slow to respond or timeout settings too low
28**Solution:**
29```yaml
30originRequest:
31  connectTimeout: 60s
32  tlsTimeout: 20s
33  keepAliveTimeout: 120s
34```
35 
36### "Tunnel not starting"
37 
38**Cause:** Invalid config, missing credentials, or tunnel doesn't exist
39**Solution:**
40```bash
41cloudflared tunnel ingress validate  # Validate config
42ls -la ~/.cloudflared/*.json         # Verify credentials
43cloudflared tunnel list              # Verify tunnel exists
44```
45 
46### "Connection already registered"
47 
48**Cause:** Multiple replicas with same connector ID or stale connection
49**Solution:**
50```bash
51# Check active connections
52cloudflared tunnel info my-tunnel
53 
54# Wait 60s for stale connection cleanup, or restart with new connector ID
55cloudflared tunnel run my-tunnel
56```
57 
58### "Tunnel credentials rotated but connections fail"
59 
60**Cause:** Old cloudflared processes using expired credentials
61**Solution:**
62```bash
63# Stop all cloudflared processes
64pkill cloudflared
65 
66# Verify stopped
67ps aux | grep cloudflared
68 
69# Restart with new credentials
70cloudflared tunnel run my-tunnel
71```
72 
73## Limits
74 
75| Resource/Limit | Value | Notes |
76|----------------|-------|-------|
77| Free tier | Unlimited tunnels | Unlimited traffic |
78| Tunnel replicas | 1000 per tunnel | Max concurrent |
79| Connection duration | No hard limit | Hours to days |
80| Long-lived connections | May drop during updates | WebSocket, SSH, UDP |
81| Replica registration | ~5s TTL | Old replica dropped after 5s no heartbeat |
82| Token rotation grace | 24 hours | Old tokens work during grace period |
83 
84## Best Practices
85 
86### Security
871. Use token-based tunnels (config source: cloudflare) for centralized control
882. Enable Access policies for sensitive services
893. Rotate tunnel credentials regularly
904. After rotation: stop all old cloudflared processes within 24h grace period
915. Verify TLS certs (`noTLSVerify: false`)
926. Restrict `bastion` service type
93 
94### Performance
951. Run multiple replicas for HA (2-4 typical, load balanced automatically)
962. Replicas share same tunnel UUID, get unique connector IDs
973. Place `cloudflared` close to origin (same network)
984. Use HTTP/2 for gRPC (`http2Origin: true`)
995. Tune keepalive for long-lived connections
1006. Monitor connection counts
101 
102### Configuration
1031. Use environment variables for secrets
1042. Version control config files
1053. Validate before deploying (`cloudflared tunnel ingress validate`)
1064. Test rules (`cloudflared tunnel ingress rule <URL>`)
1075. Document rule order (first match wins)
108 
109### Operations
1101. Monitor tunnel health in dashboard (shows active replicas)
1112. Set up disconnect alerts (when replica count drops to 0)
1123. Graceful shutdown for config updates
1134. Update replicas in rolling fashion (update 1, wait, update next)
1145. Keep `cloudflared` updated (1 year support window)
1156. Use `--no-autoupdate` in prod; control updates manually
116 
117## Debug Mode
118 
119```bash
120cloudflared tunnel --loglevel debug run my-tunnel
121cloudflared tunnel ingress rule https://app.example.com
122```
123 
124## Migration Strategies
125 
126### From Ngrok
127```yaml
128# Ngrok: ngrok http 8000
129# Cloudflare Tunnel:
130ingress:
131  - hostname: app.example.com
132    service: http://localhost:8000
133  - service: http_status:404
134```
135 
136### From VPN
137```yaml
138# Replace VPN with private network routing
139warp-routing:
140  enabled: true
141```
142 
143```bash
144cloudflared tunnel route ip add 10.0.0.0/8 my-tunnel
145```
146 
147Users install WARP client instead of VPN.
148