worker-shell: exec fails with "Cannot read properties of undefined (reading 'WorkspaceServiceProxy')" because the required enable_ctx_exports compat flag is undocumented

[ryanramtin]

Summary

Following the README's worker-shell quick start verbatim produces a runtime failure on the first exec, with an error naming a symbol the reader never wrote:

TypeError: Cannot read properties of undefined (reading 'WorkspaceServiceProxy')

There are two independent causes, and they produce the identical message. That's what makes this expensive: fixing one gives no signal you made progress, because the error doesn't change.

1. The Worker doesn't re-export the class — export { WorkspaceServiceProxy } from "@cloudflare/computer"
2. compatibility_flags is missing enable_ctx_exports, so ctx.exports is undefined

Cause 2 appears to be undocumented. The README's worker-shell section lists nodejs_compat and experimental and the Worker Loader binding, but not enable_ctx_exports. I found the flag name by grepping strings out of the workerd binary.

The failing read is backends/worker-shell/index.js:

env: { HOST: ctx.exports.WorkspaceServiceProxy({ props: workspace }) },

ctx.exports is gated behind enable_ctx_exports; without the flag the property access throws before WorkspaceServiceProxy is ever consulted — hence the misleading symbol name in the message.

Reproduce

@cloudflare/computer@0.2.0, wrangler@4.123.0, workerd@1.20260811.1.

Build the README's worker-shell quick start exactly as written, then:

curl -X POST localhost:8787/exec -H 'content-type: application/json' -d '{"cmd":"echo hi"}'

Expected: hi
Actual: TypeError: Cannot read properties of undefined (reading 'WorkspaceServiceProxy')

Adding enable_ctx_exports to compatibility_flags fixes it, provided the class is also re-exported.

Suggested fix

Either would have saved the debugging time; the first is the cheap one:

1. Document the flag. Add enable_ctx_exports to the worker-shell setup section and the "Choosing a backend" table's Needs column, alongside the experimental flag and Worker Loader binding.
2. Fail with a message that names the cause. Guard the ctx.exports access and throw something that distinguishes the two cases, e.g. "ctx.exports is undefined — add enable_ctx_exports to compatibility_flags" vs "WorkspaceServiceProxy is not exported from your Worker — add export { WorkspaceServiceProxy }".

Happy to open a PR for the docs change if useful.

Context

Hit while building a local rig against the isolate backend. Everything else worked well once past this — persistent filesystem across restarts, shell exec, shared store between fs and the shell, and egress control were all straightforward.

[ryanramtin]

Correction from the reporter — I overstated this

I dug further before proposing a patch, and my original diagnosis is partly wrong. Correcting it here so nobody spends time on the wrong fix.

ctx.exports is gated by compatibility date, not only by the flag. The enable-by-default date is 2025-11-17. Bisected against workerd@1.20260811.1, same Worker, only the date changed:

compatibility_date	exec result
2025-11-16	fails — Cannot read properties of undefined (reading 'WorkspaceServiceProxy')
2025-11-17	works

My repro used 2025-11-01, six weeks before the cutoff. That's why I hit it and why examples/worker-shell (compatibility_date: 2026-05-26) does not. I re-ran my rig at the example's exact date with no enable_ctx_exports flag and it passed — so the examples are fine, and the flag is not a missing requirement for anyone on a current compatibility date.

So please disregard the "undocumented required flag" framing and the suggested Needs-column edit. enable_ctx_exports is only relevant as a back-compat escape hatch for a pre-2025-11-17 date.

What I think still stands

A smaller, genuinely confusing thing: when ctx.exports is undefined, the failure surfaces as a TypeError naming WorkspaceServiceProxy — a symbol pointing at the export the reader did wire up, not at the actual cause (the compatibility date). worker-shell.ts already notes that ctx.exports is runtime-only and untyped:

// Subset of DurableObjectState the backend needs. ctx.exports is
// present at runtime but not in the public type today; ...

A guard at the point of use would name the real cause:

if (!ctx.exports) {
  throw new Error(
    "ctx.exports is unavailable. The worker-shell backend needs it to expose " +
    "WorkspaceServiceProxy to the Dynamic Worker. Set compatibility_date to " +
    "2025-11-17 or later (or add the enable_ctx_exports compatibility flag).",
  );
}

Entirely your call whether that's worth the branch — with a current compat date nobody reaches it. Happy for this to be closed as not-a-bug if you'd rather keep the code lean; the corrected date threshold is now on the record either way.

Apologies for the noise in the original report. #106 (the sqlite3 packaging gap) is unaffected by this and reproduces on a clean install.