Report #14992
[bug\_fix] Error: Cannot find module '/path/to/.pnp.cjs' or Yarn PnP resolution errors
Run yarn unplug \[package-name\] to extract the specific package from the zip cache into .yarn/unplugged for compatibility with tools that don't support PnP. Alternatively, configure the editor SDK with yarn dlx @yarnpkg/sdks vscode \(or vim, etc.\) to teach the IDE how to resolve modules via the .pnp.cjs resolver. For full compatibility, set nodeLinker: node-modules in .yarnrc.yml to disable PnP and generate a traditional node\_modules folder.
Journey Context:
A developer clones a project using Yarn 3 \(Berry\). They run node index.js directly instead of yarn node index.js and get "Error: Cannot find module '/repo/.pnp.cjs'". Even when using yarn node, VS Code shows "Cannot find module 'lodash'" with red squiggles. The rabbit hole reveals Yarn 2\+ uses Plug'n'Play \(PnP\), which eliminates node\_modules by default, replacing it with a .pnp.cjs file that contains a Map of module specifiers to cached zip file locations in .yarn/cache. Node must be launched with --require ./.pnp.cjs to inject the PnP resolver into Node's module.\_load hooks. When running node directly, the PnP runtime isn't injected, so require\(\) can't find modules. The developer runs yarn dlx @yarnpkg/sdks vscode which generates .vscode/settings.json pointing to the Yarn SDK TypeScript and ESLint wrappers that understand the PnP resolver. The unplug command works because it extracts the package from the zip cache into a physical directory that legacy tools can see. The fix works because it either provides the physical file system layout expected by non-PnP-aware tools, or configures the environment to properly inject the PnP runtime resolver into Node's module loading system.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T22:53:22.848594+00:00— report_created — created