Who this actually affects
unstable_getMiniflareWorkerOptions is part of Wrangler’s unstable Miniflare integration API: code that programmatically builds a Miniflare-backed local Worker instance, most commonly a custom Vitest or testing-harness setup that needs finer control than plain wrangler dev gives. containerEngine configures which local container runtime backs Cloudflare’s Containers feature when a Worker uses container bindings.
The change itself, from cloudflare/workers-sdk’s packages/wrangler/CHANGELOG.md:
“Remove
containerEnginefrom the worker options returned byunstable_getMiniflareWorkerOptions”
This shipped in wrangler@4.117.0, released 2026-07-31, as part of the broader Miniflare v5 upgrade bundled into that release.
Structural Comparison Matrix
| Operational Aspect | Before (Miniflare v4-era) | After (v4.117.0+) |
|---|---|---|
Where containerEngine lives | Read off the per-worker options object returned by unstable_getMiniflareWorkerOptions | Set at the Miniflare instance level, not per-worker |
| Failure mode for old code | Field present, real value | Field absent; reads as undefined, no error thrown |
| Who is affected | Anyone using the plain wrangler dev flow: not affected | Custom harnesses calling the unstable API directly |
Fix it: move the setting to the Miniflare instance
This fails silently, not loudly
There is no thrown error, no deprecation warning printed at runtime, and no
type error unless your harness has strict typing on the returned shape. A
harness that destructures containerEngine off the worker options and passes
it along gets undefined and keeps running, which can mean local
container-backed tests silently stop using the engine you intended.
Before: reading it off worker options
const workerOptions = await unstable_getMiniflareWorkerOptions(config);
// containerEngine is now undefined here, not thrown
const engine = workerOptions.containerEngine;After: set it on the Miniflare instance directly
const workerOptions = await unstable_getMiniflareWorkerOptions(config);
const mf = new Miniflare({
...workerOptions,
containerEngine: "docker", // set at the instance level now
});The exact shape of the instance-level option depends on which Miniflare version your harness pins, so confirm the current constructor signature against your installed miniflare package version rather than copying this verbatim; the point that matters is which layer owns the setting, not the exact call shape.
Confirmed version
Sourced directly from cloudflare/workers-sdk’s packages/wrangler/CHANGELOG.md, wrangler@4.117.0, released 2026-07-31. This one wasn’t independently reproduced against a live Containers-backed harness, since that requires a container runtime and a bound Worker beyond what this post’s scope covers; the changelog entry and the API’s documented shape are the source. If your own harness pins an older Wrangler and hasn’t hit this yet, check your wrangler and miniflare versions before upgrading past 4.117.0. Browse more posts like this in the Dev Tools archive.
