references/hyperdrive/gotchas.md
Hyperdrive troubleshooting
Start with the actual error and the affected configuration. Fetch Troubleshoot and debug for current error codes and diagnosis rather than guessing from a generic connection failure.
| Symptom | What to inspect and where to read | |---------|----------------------------------| | Connection refused or authentication failure | Check origin reachability and credentials using troubleshooting and firewall/networking configuration. | | Private database or TLS failure | Follow the selected Workers VPC or Tunnel/Access path and its certificate prerequisites; see SSL/TLS configuration. | | Pool exhaustion or too many connections | Distinguish client connection lifetime from origin pool capacity. Read connection lifecycle, pool tuning, and limits. | | Query timeout | Check the current limits and metrics before changing query or transaction design. | | Stale reads or unexpectedly uncached queries | Inspect the binding's cache configuration and query eligibility in query caching. Writes do not purge cached reads; do not treat prepared-statement settings as cache controls. | | Slow multi-query requests | Inspect metrics and check whether Worker placement matches the regional database. Follow placement setup; a Hyperdrive binding alone does not place compute near the origin. | | Local connection failure, ignored environment variable, or absent cache behavior | Check binding names, local connection overrides, precedence, and remote testing in local development. | | Unsupported driver or SQL feature | Check supported databases and features and the selected driver guide. |
Capacity and changes
Retrieve limits and pricing for current plan allowances, connection and query bounds, and limit-increase guidance. Check release notes when behavior changes after an upgrade.
See configuration.md to change a configuration and patterns.md to revisit freshness or connection decisions.