1# Gotchas and Troubleshooting
2 
3Common pitfalls, limitations, and solutions for TCP Sockets in Cloudflare Workers.
4 
5## Platform Limits
6 
7### Connection Limits
8 
9| Limit | Value |
10|-------|-------|
11| Max concurrent sockets per request | 6 (hard limit) |
12| Socket lifetime | Request duration |
13| Connection timeout | Platform-dependent, no setting |
14 
15**Problem:** Exceeding 6 connections throws error
16 
17**Solution:** Process in batches of 6
18 
19```typescript
20for (let i = 0; i < hosts.length; i += 6) {
21  const batch = hosts.slice(i, i + 6).map(h => connect({ hostname: h, port: 443 }));
22  await Promise.all(batch.map(async s => { /* use */ await s.close(); }));
23}
24```
25 
26### Blocked Destinations
27 
28Cloudflare IPs (1.1.1.1), localhost (127.0.0.1), port 25 (SMTP), Worker's own URL blocked for security.
29 
30**Solution:** Use public IPs or Tunnel hostnames: `connect({ hostname: "db.internal.company.net", port: 5432 })`
31 
32### Scope Requirements
33 
34**Problem:** Sockets created in global scope fail
35 
36**Cause:** Sockets tied to request lifecycle
37 
38**Solution:** Create inside handler: `export default { async fetch() { const socket = connect(...); } }`
39 
40## Common Errors
41 
42### Error: "proxy request failed"
43 
44**Causes:** Blocked destination (Cloudflare IP, localhost, port 25), DNS failure, network unreachable
45 
46**Solution:** Validate destinations, use Tunnel hostnames, catch errors with try/catch
47 
48### Error: "TCP Loop detected"
49 
50**Cause:** Worker connecting to itself
51 
52**Solution:** Connect to external service, not Worker's own hostname
53 
54### Error: "Port 25 prohibited"
55 
56**Cause:** SMTP port blocked
57 
58**Solution:** Use Email Workers API for email
59 
60### Error: "socket is not open"
61 
62**Cause:** Read/write after close
63 
64**Solution:** Always use try/finally to ensure proper closure order
65 
66### Error: Connection timeout
67 
68**Cause:** No built-in timeout
69 
70**Solution:** Use `Promise.race()`:
71 
72```typescript
73const socket = connect(addr, opts);
74const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 5000));
75await Promise.race([socket.opened, timeout]);
76```
77 
78## TLS/SSL Issues
79 
80### StartTLS Timing
81 
82**Problem:** Calling `startTls()` too early
83 
84**Solution:** Send protocol-specific STARTTLS command, wait for server OK, then call `socket.startTls()`
85 
86### Certificate Validation
87 
88**Problem:** Self-signed certs fail
89 
90**Solution:** Use proper certs or Tunnel (handles TLS termination)
91 
92## Performance Issues
93 
94### Not Using Connection Pooling
95 
96**Problem:** New connection overhead per request
97 
98**Solution:** Use [Hyperdrive](../hyperdrive/) for databases (built-in pooling)
99 
100### Not Using Smart Placement
101 
102**Problem:** High latency to backend
103 
104**Solution:** Enable: `{ "placement": { "mode": "smart" } }` in wrangler.jsonc
105 
106### Forgetting to Close Sockets
107 
108**Problem:** Resource leaks
109 
110**Solution:** Always use try/finally:
111 
112```typescript
113const socket = connect({ hostname: "api.internal", port: 443 });
114try {
115  // Use socket
116} finally {
117  await socket.close();
118}
119```
120 
121## Data Handling Issues
122 
123### Assuming Single Read Gets All Data
124 
125**Problem:** Only reading once may miss chunked data
126 
127**Solution:** Loop `reader.read()` until `done === true` (see patterns.md)
128 
129### Text Encoding Issues
130 
131**Problem:** Using wrong encoding
132 
133**Solution:** Specify encoding: `new TextDecoder('iso-8859-1').decode(data)`
134 
135## Security Issues
136 
137### SSRF Vulnerability
138 
139**Problem:** User-controlled destinations allow access to internal services
140 
141**Solution:** Validate against strict allowlist:
142 
143```typescript
144const ALLOWED = ['api1.internal.net', 'api2.internal.net'];
145const host = new URL(req.url).searchParams.get('host');
146if (!host || !ALLOWED.includes(host)) return new Response('Forbidden', { status: 403 });
147```
148 
149## When to Use Alternatives
150 
151| Use Case | Alternative | Reason |
152|----------|-------------|--------|
153| PostgreSQL/MySQL | [Hyperdrive](../hyperdrive/) | Connection pooling, caching |
154| HTTP/HTTPS | `fetch()` | Simpler, built-in |
155| HTTP with SSRF protection | VPC Services (beta 2025+) | Declarative bindings |
156 
157## Debugging Tips
158 
1591. **Log connection details:** `const info = await socket.opened; console.log(info.remoteAddress);`
1602. **Test with public services first:** Use tcpbin.com:4242 echo server
1613. **Verify Tunnel:** `cloudflared tunnel info <name>` and `cloudflared tunnel route ip list`
162 
163## Related
164 
165- [Hyperdrive](../hyperdrive/) - Database connections
166- [Smart Placement](../smart-placement/) - Latency optimization
167- [Tunnel Troubleshooting](../tunnel/gotchas.md)
168