Troubleshooting

Diagnose deployment, binding, and execution failures.

Deploy button shows a missing repository

Cloudflare’s button requires a public repository. Confirm that the template exists on the referenced branch and the source repository is public. Private GitHub access in your browser does not give anonymous Workers Builds downloads access. See Deploy a runtime Worker for the expected flow.

Source checksum mismatch

Do not bypass verification. Confirm that runtime-source.json points to the intended immutable commit and that its digest was calculated from that exact archive. Update the pin and digest together only after reviewing the new source.

Build cannot find a workspace package

Deploy the complete isolated templates/<language> directory. Do not point a button directly at packages/<language>: it depends on build-time workspace source. For npm-based deployment, wait for publication or install a locally packed runtime. See Deploy a runtime Worker for the deploy-button and CLI paths.

The runtime has no public URL

This is expected. Public and preview URLs are disabled. Call it through a Service Binding in another Worker — see Wrangler configuration.

Binding unavailable or wrong language

Check the deployed Worker name and account against your Wrangler configuration. In local development, ensure the engine’s Wrangler process is running. A Service Binding always targets exactly one runtime Worker — there is no language field in the request to route it elsewhere. If you need another language, bind to that runtime’s Worker (or, on the Playground gateway, call /execute/<language>).

`Unknown binding 'X'`

createCodeContext({ binding }) (or runCode({ binding })) named a binding that either doesn’t exist in your env or doesn’t match /^[A-Za-z_][A-Za-z0-9_]*$/. Check the binding name against the services entries in your own wrangler.jsonc (see Bindings) — it must match exactly, including case. This validation is specific to stateful mode’s createCodeContext/binding-based runCode; the free, stateless runCode(env.X, code) does not probe env.X upfront the same way, so an unusable target there fails as a plain JavaScript error instead of this ValidationFailedError.

`Binding 'X' is not a sandbox-workers runtime Worker`

The named binding exists but either has no fetch method (for example, you passed env.Sandbox itself, or a non-Service-Binding value) or its GET /interpreter response didn’t parse as { language, engine, contexts }. Make sure the binding points at a @sandbox-workers/<language> Worker, not some other service, and that both Workers are deployed from compatible versions.

Code context not found after the runtime Worker’s interpreter expired

runCode against an existing context throws ContextNotFoundError, even though sandbox.getInfo() still lists the context. This means the runtime Worker’s Interpreter Durable Object expired (INTERPRETER_IDLE_TTL_MS) before the sandbox’s own idle timer (SANDBOX_IDLE_TTL_MS) did, so the memory snapshot backing that context is gone while the sandbox’s registry hadn’t caught up yet. The sandbox drops the context’s row once it observes this failure — create a new context to continue. To prevent this going forward, set INTERPRETER_IDLE_TTL_MS to at least SANDBOX_IDLE_TTL_MS (see Sandboxes and Environment variables).

Mismatched idle TTLs

If sandboxes seem to lose context state well before your configured SANDBOX_IDLE_TTL_MS, check the runtime Worker’s own INTERPRETER_IDLE_TTL_MS — it defaults to 24 hours independently of whatever you set on the caller side, and a shorter value there (for example, a Playground-style deployment left at its short default) expires interpreters first. Set both explicitly and keep the runtime Worker’s value at least as large as the caller’s.