#Error: Unable to start push

4 messages · Page 1 of 1 (latest)

humble glade
zinc deltaBOT
#

Hi @humble glade. 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 mention the specific IsolateNotClean: Selected isolate was not clean error, so I can’t give a definitive cause or fix. I can only infer from similar “Unable to start push” / 400–500 errors.

From the threads, we know:

  • Many push/start errors are transient backend issues or deployment-state glitches that resolve after some time or a CLI/backend upgrade. [BadDeployKey thread]
  • Some errors are tied to specific Convex CLI/backend versions and were fixed by upgrading to a newer version (e.g. 1.26 → 1.26.1). [schemaChange indexDiffs]
  • Others are caused by problematic modules or environment-variable access during analysis, and only show up as “Hit an error while pushing” until the underlying issue is fixed. [R2 env vars; env JSON error]

Given that, practical steps you can try:

  1. Upgrade Convex CLI
    Make sure you’re on the latest convex package (both CLI and backend often fix push issues in patch releases). [schemaChange indexDiffs]

  2. Restart local backend & CLI

    • Stop convex dev and any local Convex Docker/instance you might be running.
    • Kill any stray node/Convex processes using that port.
    • Restart with npx convex dev --local (or --once if that’s your flow).
#

  1. Check for “analysis-time” errors in your code
    Several “Hit an error while pushing” cases were ultimately due to code that throws during module load (e.g. reading env vars at top level, misconfigured R2, or problematic dependencies). [R2 env vars; env JSON error]

    • Temporarily comment out recent changes in Convex functions/components.
    • Especially remove any process.env access or third‑party client initialization at the top level of modules and move them inside functions.

  2. Wait and retry / new dev deployment
    In some cases, the deployment/backend state was temporarily bad and later recovered or was fixed by creating a fresh dev deployment. [BadDeployKey thread]

    • If you’re using a cloud dev deployment, you can try creating a new dev environment and pointing .env.local’s CONVEX_DEPLOYMENT to it.

Because IsolateNotClean isn’t documented in the provided sources, if these steps don’t help, the best next move is to open a support ticket or post in the Convex Discord with:

  • Full CLI version (npx convex --version)
  • OS and Node version
  • Whether this is --local or cloud dev
  • Any recent code changes in convex/ just before the error started.

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