[miniflare] Local explorer disk service incompatible with Yarn PnP

[NormalGaussian]

---

What versions & operating system are you using?

System:
  OS: Linux 6.8 Ubuntu 24.04.4 LTS (Noble Numbat)
  CPU: (12) x64 AMD Ryzen 5 5600X 6-Core Processor
  Shell: 5.2.21 - /bin/bash
Binaries:
  Node: 25.9.0
  Yarn: 4.14.1
  npm: 11.12.1
Packages (yarn info --name-only):
  miniflare@npm:4.20260426.0
  wrangler@npm:4.86.0
  @cloudflare/workerd-linux-64@npm:1.20260429.1
  @cloudflare/puppeteer@npm:1.1.0

Please provide a link to a minimal reproduction

https://github.com/NormalGaussian/wrangler-pnp-local-explorer-repro

Describe the Bug

When running wrangler dev in a project that uses Yarn with Plug'n'Play (nodeLinker: pnp, the Yarn 4 default), miniflare crashes at startup with:

Directory named "core:local-explorer-disk" not found: <path>/miniflare-npm-<ver>.zip/node_modules/miniflare/dist/local-explorer-ui

Root cause: miniflare's local explorer registers a workerd disk service pointing at dist/local-explorer-ui inside the miniflare package (packages/miniflare/src/plugins/core/explorer.ts:129, called from packages/miniflare/src/plugins/core/index.ts:1149-1180). Under Yarn PnP, packages live as zip archives in .yarn/cache/. PnP patches Node's fs so existsSync reads into those zips transparently, so miniflare's pre-flight check passes — but workerd is a separate native process with no PnP awareness and cannot read the zip as a directory, so it fails late with the cryptic error above.

This regressed for PnP users when the local explorer was switched on by default in #12848 — X_LOCAL_EXPLORER defaults to true in getLocalExplorerEnabledFromEnv (packages/workers-utils/src/environment-variables/misc-variables.ts:343-347), and that flows into unsafeLocalExplorer in packages/wrangler/src/dev/miniflare/index.ts:1059 and the Vite plugin (packages/vite-plugin-cloudflare/src/miniflare-options.ts:469,674).

Workarounds:

• X_LOCAL_EXPLORER=false wrangler dev
• yarn unplug miniflare (extracts miniflare to .yarn/unplugged/ so workerd can read it)

Suggested fixes (in order of effort):

1. Detect Yarn PnP at startup (e.g. process.versions.pnp is set) and either skip the local-explorer disk service with a warning, or transparently copy local-explorer-ui to a temp dir and point workerd there.
2. Always copy the UI assets to a temp directory at startup so miniflare doesn't depend on its own __dirname being a real filesystem path. This also helps with bundlers that flatten __dirname.

Please provide any relevant error logs

In the original (non-containerised) project, the visible error is:

Directory named "core:local-explorer-disk" not found: <path>/dist/local-explorer-ui

In the Docker repro, the same root cause surfaces as a cascading TypeError in getFreshSourceMapSupport because miniflare/wrangler tries to source-map workerd's structured stderr by reading into another PnP zip (@cspotcode/source-map-support) and throws — eating the original log line. Both manifestations go away with X_LOCAL_EXPLORER=false. Stack:

TypeError: Cannot read properties of undefined (reading '/root/.yarn/berry/cache/@cspotcode-source-map-support-npm-0.8.1-964f2de99d-10c0.zip/node_modules/@cspotcode/source-map-support/source-map-support.js')
    at Object.getFreshSourceMapSupport (file:///.../miniflare/dist/src/index.js:76883:40)
    at getSourceMappingPrepareStackTrace (file:///.../wrangler/wrangler-dist/cli.js:62528:29)
    at getSourceMappedString (file:///.../wrangler/wrangler-dist/cli.js:62576:24)
    at handleStructuredLogs (file:///.../wrangler/wrangler-dist/cli.js:65316:25)
    ...
MiniflareCoreError [ERR_RUNTIME_FAILURE]: The Workers runtime failed to start.

[edmundhung]

@NormalGaussian Thanks for the repro, this was really helpful.

I have put up a fix in #13767 and confirmed it resolves the issue in the repro you linked. I’ll try to get this landed next week.

In the meantime, it would be really helpful if you could try the prerelease in your project and let us know if you still run into any issues:

yarn add -D https://pkg.pr.new/wrangler@13767

[NormalGaussian]

That fixes it. In my original repo and a handful of others. Thanks for your work on this!