ERR_PNPM_WORKSPACE_PKG_NOT_FOUND: Fix pnpm Workspace Package Errors

Read the error literally#

Suppose an application declares:

1
{
2
  "dependencies": {
3
    "@acme/ui": "workspace:*"
4
  }
5
}

pnpm must find a workspace package whose own manifest contains:

1
{
2
  "name": "@acme/ui",
3
  "version": "1.0.0"
4
}

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:

1
.
2
├── package.json
3
├── pnpm-lock.yaml
4
├── pnpm-workspace.yaml
5
├── apps/
6
│   └── web/
7
│       └── package.json
8
└── packages/
9
    └── ui/
10
        └── package.json

The workspace file must include the package directory:

1
packages:
2
  - 'apps/*'
3
  - '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.

Use a repeatable diagnosis sequence#

Start with the package named in the error and work outward:

1. Print the current directory. Confirm it is the repository root used by the workspace.
2. Open the consumer manifest. Copy the dependency key exactly, for example @acme/ui.
3. Open the candidate package manifest. Check that its name field is exactly the same.
4. Trace the path against the workspace glob. Confirm the package directory is included by pnpm-workspace.yaml.
5. Check the protocol. Keep workspace:*, workspace:^, or another intentional workspace: range when the dependency must be local.
6. 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:

1
pwd
2
sed -n '1,160p' pnpm-workspace.yaml
3
node -p "require('./packages/ui/package.json').name"
4
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#

1
packages:
2
  - 'packages/*'

1
packages:
2
  - 'packages/*'
3
  - 'packages/design/**'

1
{
2
  "name": "@acme/design-system"
3
}

Avoid the misleading fixes#

• Do not replace workspace:* with * merely to make pnpm install pass.
• Do not add a broad ** glob without checking which directories will become workspace packages.
• Do not rename packages based only on their folders; the name field 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#