Skip to content
Back to the playbook

Diagnosing Neon serverless driver WebSocket connection failures

NeonCloudflare Workersrevision 1

Diagnostic tree

  1. In progressEvery WebSocket attempt to Neon failed@neondatabase/serverless is built for runtimes, like Cloudflare Workers, that cannot open a raw outbound TCP connection to Postgres — it instead connects through Neon's own WebSocket proxy. This error means every attempt at that WebSocket handshake failed.
View the whole map (7 more steps)
  • Confirm the connection string is the one Neon issues for this project, unmodified
  • Does the same code and connection string work outside the Worker?
  • Wrong connection string or credentials
  • Something in the Worker environment specifically is misconfigured
  • Use the connection string and driver import Neon issues for this runtime, unmodified
  • Confirm the query succeeds from inside the deployed Worker
  • Resolved

What to test

Every WebSocket attempt to Neon failed

@neondatabase/serverless is built for runtimes, like Cloudflare Workers, that cannot open a raw outbound TCP connection to Postgres — it instead connects through Neon's own WebSocket proxy. This error means every attempt at that WebSocket handshake failed.

What happened?

Passed