ERR_PNPM_WORKSPACE_PKG_NOT_FOUND: Fix pnpm Workspace Package Errors
ERR_PNPM_WORKSPACE_PKG_NOT_FOUND means pnpm cannot find a workspace package with the name requested by a dependency. The directory may exist, and its package.json may be valid, but pnpm still rejects the install when the package is not included by the workspace definition or its name does not match the dependency key.
Fix the identity and discovery boundary in that order: confirm the package name, confirm the root pnpm-workspace.yaml includes the package path, then use the workspace: protocol for a dependency that must resolve locally.
Read the error literally
Suppose an application declares:
{ "dependencies": { "@acme/ui": "workspace:*" }}pnpm must find a workspace package whose own manifest contains:
{ "name": "@acme/ui", "version": "1.0.0"}The folder name does not establish the package identity. packages/ui, packages/UI, and @acme/ui are different pieces of information. The dependency key must match the name field exactly, including scope, spelling, and case.
The workspace: protocol makes the requirement explicit. pnpm’s workspace documentation says it will refuse to resolve a package from the registry when the requested workspace package cannot be found. That is useful protection: changing workspace:* to a normal version may hide a broken monorepo link by downloading a package instead.
Check the root workspace file
A pnpm workspace needs a pnpm-workspace.yaml file at the workspace root. A minimal layout looks like this:
.├── package.json├── pnpm-lock.yaml├── pnpm-workspace.yaml├── apps/│ └── web/│ └── package.json└── packages/ └── ui/ └── package.jsonThe workspace file must include the package directory:
packages: - 'apps/*' - 'packages/*'The pnpm settings reference documents these package globs. If the packages field is omitted, only the workspace root is included. A package nested below another directory may need a recursive pattern such as components/**; do not assume that packages/* also includes packages/design/ui.
Run checks from the directory that contains pnpm-workspace.yaml. A common CI failure is running pnpm install from a subdirectory, where the intended workspace root is no longer the directory pnpm discovers.
Check the workspace-root boundary before using ../
The current pnpm settings reference allows . and .. segments in packages patterns, but the behavior is still version-sensitive. An open pnpm issue reports that a workspace rooted in frontend/ with ../docs as a package worked on pnpm 10.x but failed on pnpm 11.x with both ERR_PNPM_WORKSPACE_PKG_NOT_FOUND and a catalog-resolution error. The report is an upstream reproduction, not a confirmed fix or a guarantee that every pnpm 11 project fails.
Use this boundary table before treating an external directory as an ordinary workspace member:
| Layout or symptom | What the evidence supports | Next action |
|---|---|---|
| The package is below the workspace root and matches a normal glob | pnpm’s current settings reference supports the pattern | Fix the manifest name and glob, then keep workspace: if the dependency must be local. |
The package is reached through a ../ pattern | pnpm 11 has an open upstream report for broken workspace and catalog resolution | Pin the pnpm major in CI and reproduce the exact layout; if it fails, move the workspace file to a common root or stop treating the package as a workspace member. |
| The package is intentionally outside the workspace | It is not a local member that workspace:* can require | Use a published version, an explicit Git dependency, or another delivery method instead of weakening workspace:. |
Check the version in the same environment as the failing install:
pnpm --versionThe current pnpm workspace documentation says that workspace: refuses to resolve a missing local package from the registry. The pnpm 11 issue narrows the extra case: a package that is present on disk can still be unavailable to workspace resolution when the layout crosses the workspace root on that major version.
Use a repeatable diagnosis sequence
Start with the package named in the error and work outward:
- Print the current directory. Confirm it is the repository root used by the workspace.
- Open the consumer manifest. Copy the dependency key exactly, for example
@acme/ui. - Open the candidate package manifest. Check that its
namefield is exactly the same. - Trace the path against the workspace glob. Confirm the package directory is included by
pnpm-workspace.yaml. - Check the protocol. Keep
workspace:*,workspace:^, or another intentionalworkspace:range when the dependency must be local. - Install again from the root. Let pnpm regenerate or validate the lockfile only after the identity and glob are correct.
Useful read-only checks are simple shell commands:
pwdsed -n '1,160p' pnpm-workspace.yamlnode -p "require('./packages/ui/package.json').name"node -p "require('./apps/web/package.json').dependencies['@acme/ui']"Replace the paths with the package named in your error. If the node commands fail, fix the manifest path first; if they return different names, fix the package identity or consumer dependency. These commands do not prove that a glob includes a package, so inspect the workspace patterns separately.
Common causes and precise fixes
The workspace file is missing or in the wrong directory
Create pnpm-workspace.yaml at the root that owns the applications and packages. Do not place it only inside packages/; pnpm needs the file to define the workspace boundary.
The glob excludes the package
Change a pattern such as:
packages: - 'packages/*'to a pattern that matches the actual nesting, for example:
packages: - 'packages/*' - 'packages/design/**'Keep exclusions intentional. A leading ! pattern can remove a directory that another broad pattern included, so review the whole file rather than adding more globs until the error disappears.
The folder and name field disagree
This package is discovered by its manifest name, not by a guessed folder-to-package conversion:
{ "name": "@acme/design-system"}The consumer must use @acme/design-system. Renaming only the folder or only the dependency key leaves the workspace inconsistent. Update both sides deliberately, then update the lockfile through a normal install.
The dependency is expected to be local but uses a registry range
Use workspace:* or the range appropriate for your release policy. pnpm then fails early if the local package is unavailable instead of silently selecting a registry version. This is especially important for CI, where a missing workspace package can otherwise look like a successful install followed by a runtime mismatch.
The package is outside the intended workspace
If the package is a separate repository or intentionally published dependency, do not force it into workspace:. Use a normal version, a supported Git dependency, or another explicit delivery method. The pnpm Git dependency guide covers SSH-related CI setup when the source is intentionally outside the workspace.
Avoid the misleading fixes
- Do not replace
workspace:*with*merely to makepnpm installpass. - Do not add a broad
**glob without checking which directories will become workspace packages. - Do not rename packages based only on their folders; the
namefield is the public identity. - Do not run the repair from a nested directory and assume CI discovers the same root.
- Do not delete the lockfile as the first response. A stale lockfile can be a follow-up issue, but it does not make an undiscovered package part of the workspace.
The goal is a workspace where package discovery, manifest identity, and dependency protocol all tell the same story. Once those three boundaries align, the error usually disappears without special install flags.
FAQ
Q: Why does pnpm report a missing package when the folder exists?
A: pnpm resolves workspace dependencies by package identity and workspace membership. The folder may be excluded by the glob, or its package.json name may differ from the dependency key.
Q: Does workspace:* install from npm if the local package is missing?
A: No. pnpm documents the workspace protocol as a local-workspace requirement and refuses to resolve the package from the registry when it cannot find the requested workspace package.
Q: Where should pnpm-workspace.yaml be located?
A: Put it at the workspace root, alongside the root package.json. Its packages patterns define which application and package directories belong to the workspace.
Q: Should I use a recursive glob for every package?
A: Only when the repository layout requires it. Start with the narrowest patterns that include the intended packages, then add a recursive pattern for deeper nesting and review exclusions carefully.
References: