WebSocket error message

[sonic crown]

I’m using a monorepo with Bun, and I have a packages/convex package. When I run convex dev, after selecting a project, I get the following error:

WebSocket error message: Unexpected server response: 101
WebSocket closed with code 1006
Attempting reconnect in 573ms

I’m not sure what’s causing it.

[remote anvil]

Hi @sonic crown. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

The knowledge sources don’t describe this exact Unexpected server response: 101 / WebSocket closed with code 1006 situation, so I can’t say with certainty what’s wrong in your setup.

What we do know:

• Convex’s JS clients (including when used with Bun) connect over WebSockets and will automatically reconnect when the connection drops. [Convex React client]
• You can override the WebSocket implementation via webSocketConstructor in BaseConvexClientOptions, which is how Convex talks to the deployment in non‑browser environments like Bun. [Base client options]
• When the server encounters an internal error, it may close the WebSocket with an internal‑error code (1011 is the “500‑like” code; 1006 is the “abnormal closure” the client sees when the close frame isn’t received). [WebSocket internal error]

Given that:

• The error is happening right after you select a project in convex dev, before your own code runs.
• Other users have hit various network / deployment issues that manifested as 5xx or 503 errors when the CLI tried to talk to the deployment. [Service unavailable example; “request couldn’t be completed” 500]

So the most likely categories (but not confirmed from docs) are:

1. Network / deployment availability issue (temporary 5xx / 503 from your Convex deployment causing the WebSocket handshake to fail).
2. Environment / tooling interaction (Bun + monorepo path / execution context causing the CLI or WebSocket client to misbehave), similar to other Bun‑related oddities reported with convex import and CLI prompts. [Bun import issues]

Because the docs don’t give a direct fix, the safest next steps are:

1. Check deployment health from your machine

   Run:

   npx convex network-test
   

   (or bunx convex network-test in the same directory you’re running convex dev from) and see if HTTPS checks succeed, similar to the example here. [Network test example]

2. Try outside the monorepo package

   From the monorepo root, create a fresh Convex app in a sibling directory (not under packages/) and run bunx convex dev there, following the Bun quickstart. [Bun quickstart]

   • If that works, the issue is likely related to how packages/convex is wired (cwd, env vars, or tooling).

3. Check for transient Convex service issues

   Since other users have seen temporary 5xx/503s from Convex that later resolved, it’s worth retrying after a bit and checking the Convex status / Discord announcements. [Service unavailable example]

4. If you’re on a paid plan, open a support ticket

   For internal server / WebSocket issues that block you, Convex staff recommend opening a support issue via the dashboard so they can inspect logs. [Internal error guidance]

Because the sources don’t document this exact error pattern, I can’t provide a precise root cause. If you can share:

• The exact command you run (bunx convex dev vs npx convex dev)
• The directory you run it from (monorepo root vs packages/convex)
• Whether npx convex network-test passes

then I can help you narrow it down further within what’s covered by the docs.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@sonic crown Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[sonic crown]

@remote anvil after i run npx convex network-test I get:
You don't have access to the selected project. Run npx convex dev to select a different project.

[remote anvil]

Let me check the knowledge base for you again. One moment! :books:

---

That npx convex network-test message means the CLI is currently pointed at a Convex project/deployment your account (or local anonymous setup) no longer has permission to access. This is consistent with how the CLI uses the saved project configuration in .env.local / CONVEX_DEPLOYMENT and your local credentials. [CLI configure; Dev workflow]

Given your original WebSocket errors and this message, the next concrete steps (all based on documented behavior) are:

1. Re‑select / reconfigure the project

   From the directory where you’re running Convex:

   npx convex dev
   

   If there’s no valid CONVEX_DEPLOYMENT or you don’t have access to the current one, convex dev will walk you through either:

   • logging in and selecting/creating a project, or
   • starting a local (anonymous) deployment. [CLI configure; Dev workflow]

   Once that completes successfully, the correct deployment name will be written to .env.local.

2. Then re‑run the network test

   After npx convex dev has successfully synced once:

   npx convex network-test
   

   Now it should test against the deployment you just configured, instead of the inaccessible one. [Network test example]

3. If you want to avoid cloud access issues, try a local deployment

   Since you’re debugging WebSocket issues and permissions, you can also run a purely local deployment:

   npx convex dev --local --once
   

This creates/uses a local backend that doesn’t depend on cloud project permissions. [Local deployments]

If, after reconfiguring with npx convex dev, you still see the WebSocket 101 / 1006 errors, the knowledge sources don’t provide a documented, specific cause for that combination. In that case, the next best step (noted in other support threads) is to contact Convex support via the dashboard so they can inspect deployment logs, since it may be an internal or environment‑specific issue not covered in the docs.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@sonic crown Kapa.ai is still learning and improving, please let me know how I did by reacting below.