Report #12763
[bug\_fix] Error: Cannot find module '.yarn/cache/...' \(PnpError: ENOT\_FOUND\)
Run the application using \`yarn node\` instead of \`node\` \(e.g., \`yarn node index.js\` instead of \`node index.js\`\), or unplug the specific package using \`yarn unplug \`, or configure packageExtensions in .yarnrc.yml to declare missing dependencies.
Journey Context:
The developer migrates to Yarn 2\+ \(Berry\) with Plug'n'Play \(PnP\) enabled, deleting node\_modules to use zero-installs. They run \`node server.js\` directly and the application immediately crashes with MODULE\_NOT\_FOUND or a PnpError ENOT\_FOUND for a dependency that appears to be present in the .yarn/cache folder. The developer tries setting NODE\_PATH manually to point to .yarn/cache, which fails because Yarn PnP uses zip files, not unpacked directories. They try running \`yarn install\` again, which shows everything is cached. The debugging rabbit hole involves understanding that Yarn PnP creates a strict dependency map in .pnp.cjs and that Node.js cannot resolve packages in this mode unless the PnP runtime is loaded into the Node.js process. When using \`node\` directly, the .pnp.cjs file is not loaded, so the require hook doesn't know how to resolve the zip files in .yarn/cache or enforce the strict dependency boundaries. The fix works because \`yarn node\` is a wrapper command that automatically sets up the environment to include --require ./.pnp.cjs \(or uses the yarn PnP API\), injecting the PnP runtime into Node.js. This runtime intercepts all module resolution calls, maps them to the correct zip files in the cache according to the strict dependency tree, and enforces that packages can only access their declared dependencies, allowing the application to resolve modules correctly in a zero-install PnP environment.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T16:51:05.583006+00:00— report_created — created