Diagnosing Neon serverless driver WebSocket connection failures

Symptoms

• `Error: All attempts to open a WebSocket to connect to the database failed` from @neondatabase/serverless
• Happens specifically inside an edge runtime such as Cloudflare Workers
• The same-looking code may work fine in a regular Node.js process

The diagnostic path

8 steps, exactly as this revision published them.

1. Step 1 · StartEvery 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 happens next

   • passed → step 2, Confirm the connection string is the one Neon issues for this project, unmodified

2. Step 2 · TestConfirm the connection string is the one Neon issues for this project, unmodified

   Copy it directly from the Neon project dashboard's connection details rather than reusing a generic postgres:// string meant for a raw TCP client like psql or node-postgres, and rather than hand-editing it.

   What happens next

   • passed → step 3, Does the same code and connection string work outside the Worker?
   • failed → step 4, Wrong connection string or credentials
   • unknown → step 4, Wrong connection string or credentials

3. Step 3 · TestDoes the same code and connection string work outside the Worker?

   Run the identical query against the identical connection string from a plain Node.js process (with a WebSocket implementation available). If it works there but not inside the deployed Worker, the issue is specific to the Worker runtime rather than the credentials or endpoint.

   What happens next

   • passed → step 5, Something in the Worker environment specifically is misconfigured
   • failed → step 4, Wrong connection string or credentials
   • unknown → step 4, Wrong connection string or credentials

4. Step 4 · Root causeWrong connection string or credentials

   The string doesn't match what Neon currently issues for this project/branch — it may have been copied from an old branch, a different project, or edited by hand and had something break in the process.

   What happens next

   • passed → step 6, Use the connection string and driver import Neon issues for this runtime, unmodified

5. Step 5 · Root causeSomething in the Worker environment specifically is misconfigured

   Check that the code imports the driver's default export meant for edge runtimes rather than a Node-targeted entry point, and that nothing is calling neonConfig.webSocketConstructor unnecessarily inside the Worker — Workers provide a native global WebSocket, and forcing a Node ws polyfill there can break the handshake instead of fixing it. Also rule out the Worker hitting its own CPU/wall-clock limit before the handshake completes.

   What happens next

   • passed → step 6, Use the connection string and driver import Neon issues for this runtime, unmodified

6. Step 6 · FixUse the connection string and driver import Neon issues for this runtime, unmodified

   Copy the connection string straight from the Neon dashboard, import the driver's default export, and don't set neonConfig.webSocketConstructor unless running in a non-edge Node process that lacks a native WebSocket.

   Read-onlyjavascript

   Copy

   import { neon } from "@neondatabase/serverless";
   const sql = neon(process.env.DATABASE_URL);
   const rows = await sql`SELECT 1`;

   What happens next

   • passed → step 7, Confirm the query succeeds from inside the deployed Worker

7. Step 7 · Verify the fixConfirm the query succeeds from inside the deployed Worker

   Deploy and run the same query from the actual Worker, not just locally, and confirm it returns without the WebSocket error.

   What happens next

   • passed → step 8, Resolved
   • failed → step 5, Something in the Worker environment specifically is misconfigured
   • unknown → step 5, Something in the Worker environment specifically is misconfigured

8. Step 8 · EndResolved

   Queries succeed from the deployed Worker using Neon's own connection string and the edge-runtime driver entry point.

Sources

• Neon serverless driver— Neon