Gotchas
See README.md, configuration.md, api.md, patterns.md.
Common Errors
"Too many open connections" / "Connection limit exceeded"
Cause: Workers have a hard limit of 6 concurrent connections per invocation
Solution: Set max: 5 in driver config, reuse connections, ensure proper cleanup with client.end() or ctx.waitUntil(conn.end())
"Failed to acquire a connection (Pool exhausted)"
Cause: All connections in pool are in use, often due to long-running transactions
Solution: Reduce transaction duration, avoid queries >60s, don't hold connections during external calls, or upgrade to paid plan for more connections
"connection_refused"
Cause: Database refusing connections due to firewall, connection limits, or service down
Solution: Check firewall allows Cloudflare IPs, verify DB listening on port, confirm service running, and validate credentials
"Query timeout (deadline exceeded)"
Cause: Query execution exceeding 60s timeout limit
Solution: Optimize with indexes, reduce dataset with LIMIT, break into smaller queries, or use async processing
"password authentication failed"
Cause: Invalid credentials in Hyperdrive configuration
Solution: Check username and password in Hyperdrive config match database credentials
"SSL/TLS connection error"
Cause: SSL/TLS configuration mismatch between Hyperdrive and database
Solution: Add sslmode=require (Postgres) or sslMode=REQUIRED (MySQL), upload CA cert if self-signed, verify DB has SSL enabled, and check cert expiry
"Queries not being cached"
Cause: Query is mutating (INSERT/UPDATE/DELETE), contains volatile functions (NOW(), RANDOM()), or caching disabled
Solution: Verify query is non-mutating SELECT, avoid volatile functions, confirm caching enabled, use wrangler dev --remote to test, and set prepare=true for postgres.js
"Slow multi-query Workers despite Hyperdrive"
Cause: Worker executing at edge, each query round-trips to DB region
Solution: Enable Smart Placement ("placement": {"mode": "smart"} in wrangler.jsonc) to execute Worker near DB. See patterns.md Multi-Query pattern.
"Local database connection failed"
Cause: localConnectionString incorrect or database not running
Solution: Verify localConnectionString correct, check DB running, confirm env var name matches binding, and test with psql/mysql client
"Environment variable not working"
Cause: Environment variable format incorrect or not exported
Solution: Use format CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>, ensure binding matches wrangler.jsonc, export variable in shell, and restart wrangler dev
Limits
| Limit | Free | Paid | Notes |
|---|---|---|---|
| Max configs | 10 | 25 | Hyperdrive configurations per account |
| Worker connections | 6 | 6 | Max concurrent connections per Worker invocation |
| Username/DB name | 63 bytes | 63 bytes | Maximum length |
| Connection timeout | 15s | 15s | Time to establish connection |
| Idle timeout | 10 min | 10 min | Connection idle timeout |
| Max origin connections | ~20 | ~100 | Connections to origin database |
| Query duration max | 60s | 60s | Queries >60s terminated |
| Cached response max | 50 MB | 50 MB | Responses >50MB returned but not cached |