Diagnosing and Fixing Ghost Dependencies and Version Conflicts in Yarn Berry PnP

Recognizing the Problem

When running a Yarn Berry project with Plug'n'Play (PnP) enabled, you may encounter a sudden "Module not found" error for a package that you know is installed, or see version‑mismatch warnings that only appear in CI. These symptoms usually point to one of two issues: a ghost dependency (an import that is not declared in package.json) or a version conflict where two packages require incompatible releases of the same library.

Cause and Diagnostic Overview

Symptom	Likely Cause	First Diagnostic Command
Error: Module not found for lodash (or any valid package)	Ghost dependency: the module is a sub‑dependency of another package but not listed in your package.json	yarn why lodash
Runtime hook errors or warnings about multiple versions of react	Version conflict: different packages resolve to different releases of the same library	yarn list --pattern react
Build passes locally but fails in CI	Environment mismatch: CI expects a physical node_modules folder while PnP does not create one	yarn config info (look for nodeLinker setting)

Ordered Checks

1. Confirm PnP is active – run yarn config get nodeLinker. Expect output pnp. If it shows node-modules, switch to PnP by deleting node_modules and .yarn/cache then running yarn install.
2. Trace the offending module – execute yarn why <module-name>. Examine the tree: if the module appears only under another dependency and not under the root package.json, it is a ghost dependency.
3. Check for version spread – run yarn list --pattern <module-name>. If more than one version line appears, note the versions and which dependents request them.
4. Validate lockfile integrity – run yarn workspaces focus --all (if using workspaces) or simply yarn install to ensure the lockfile matches the package.json.

Fixes Tied to Findings

Fixing a Ghost Dependency

Once yarn why shows the module is only a sub‑dependency, add it explicitly to your project:

yarn add <module-name>

This writes the package into package.json and updates the .pnp.cjs map, making the import resolvable.

Resolving a Version Conflict

If yarn list reveals multiple versions, decide which version to enforce. Add a resolutions section to the root package.json:

{
  "name": "my-project",
  "version": "1.0.0",
  "resolutions": {
    "": "",
    "**": ""
  }
}

Then run yarn install to regenerate the lockfile with the forced version.

Making a Third‑Party Package PnP‑Compatible

When a dependency fails because it expects a file‑system layout or lacks declared peer dependencies, create a patch:

yarn patch <package-name>

Edit the temporary files to add missing peerDependencies or adjust paths, then save. Yarn will generate a .patch file and apply it on subsequent installs.

Escalation Criteria

• If after adding the missing dependency the error persists, re‑run yarn why to verify that the module is now reachable from the root.
• If forcing a version with resolutions introduces runtime errors (e.g., missing methods), revert the resolution, consult the upstream libraries’ changelogs, and consider upgrading or downgrading the dependents instead of a blanket force.
• When a patch does not apply cleanly or the package updates frequently, consider forking the repository and using a resolutions pointer to your fork, or discuss upstream compatibility with the maintainers.
• If CI continues to fail despite a correct PnP setup, ensure the CI image has Yarn Berry installed and that the nodeLinker is set to pnp (some CI caches may restore a node_modules folder; clear caches before installing).

By following these steps you can turn opaque "Module not found" or version‑mismatch messages into actionable diagnostics, keep your dependency graph explicit, and maintain a stable PnP‑enabled workflow.