Resolving 'workspace: package not found' Errors in pnpm Monorepos

The Problem: Local Dependency Resolution Failure

When managing a monorepo with pnpm, you may encounter ERR_PNPM_RESOLVE_FAILURE or messages stating workspace: package not found during pnpm install. This happens when pnpm cannot map a dependency declared with the workspace: protocol to a physical directory defined in your workspace configuration.

The immediate takeaway: This is rarely a bug in pnpm itself and usually a mismatch between the pnpm-workspace.yaml definition and the package.json dependency declaration.

Diagnostic Matrix

Symptom	Likely Cause	Diagnostic Check
Immediate failure on install	Outdated pnpm version	pnpm -v
Package exists but isn't found	Missing path in workspace config	Inspect pnpm-workspace.yaml
Resolved to registry instead of local	Missing workspace: prefix	Inspect package.json
Intermittent resolution errors	Corrupt lockfile or store	Check pnpm-lock.yaml entries

Step-by-Step Resolution Path

Follow these checks in order. After applying a fix, run pnpm install to verify the resolution.

1. Version Validation

The workspace: protocol requires pnpm v6.0 or higher. Older versions do not support this syntax.

# Run this in your terminal
pnpm -v

Fix: If the version is below 6.0, upgrade the global installation:

# Run as user with global npm permissions
npm i -g pnpm@latest

2. Workspace Boundary Check

pnpm only looks for packages in directories explicitly listed in pnpm-workspace.yaml. If your package is in a folder not covered by the globs in this file, pnpm will ignore it.

Check: Open pnpm-workspace.yaml in the root directory. Ensure the path to the missing package is included.

Example Configuration:

# pnpm-workspace.yaml
packages:
  - 'packages/*' # Includes all folders in /packages
  - 'apps/*'     # Includes all folders in /apps
  - 'shared-libs' # Includes a specific directory

3. Dependency Protocol Verification

To force pnpm to resolve a package locally rather than searching the npm registry, you must use the workspace: prefix in the dependent package's package.json.

Check: Locate the package.json of the package that needs the dependency. Verify the version string.

• Incorrect: "my-local-pkg": "1.0.0" (pnpm may try to find this on the registry)
• Correct: "my-local-pkg": "workspace:*" (resolves to the latest local version)
• Correct: "my-local-pkg": "workspace:^1.0.0" (resolves to local version matching the range)

4. Linkage Inspection

If the configuration looks correct but the error persists, check if pnpm actually sees the package as part of the workspace graph.

# Run from the root of the monorepo
pnpm ls <package-name>

If the output shows a version number from the registry (e.g., my-pkg 1.2.3) instead of a local path, the workspace: protocol is not being applied.

Applying the Final Fix

If you have corrected the pnpm-workspace.yaml or package.json, a clean state is often required to clear stale resolution attempts.

1. Delete the node_modules folder in the affected packages.
2. Delete the pnpm-lock.yaml file in the root.
3. Run pnpm install.

Warning: Do not manually edit pnpm-lock.yaml. This file is a strictly managed dependency graph; manual changes often lead to checksum mismatches.

Verification and Validation

To confirm the fix is operational, verify the physical symlink. pnpm uses a content-addressable store and symlinks for workspace packages.

Navigate to the node_modules of the dependent package and check the link target:

# Linux/macOS
ls -l node_modules/my-local-pkg

The output should show a symlink pointing back to the source directory of the package within your monorepo, not to the .pnpm virtual store.

Escalation Criteria

If the package is still not found after the steps above, perform these advanced diagnostics:

• Store Pruning: Run pnpm store prune to remove unreferenced packages from the content-addressable store.
• Verbose Logging: Run pnpm install --loglevel verbose. Look for the "Resolving" phase to see exactly which directories pnpm is scanning.
• Alias Check: Ensure the name field in the target package's package.json exactly matches the dependency name used in the dependent package.