npm "No workspaces found" / "workspace not found" - Fix Monorepo Install in CI

By Kaveh Alemi·Latchkey

npm workspaces are declared by a workspaces glob in the root package.json. The error means npm could not match that glob to any package, or a --workspace target you named does not exist in the tree.

What this error means

npm install -w <name> or npm run build -w <name> fails with "No workspaces found" or that the named workspace does not exist. The root install may succeed while a per-workspace command cannot find its target.

npm output

npm error No workspaces found:
npm error   --workspace=@acme/api
# or
npm error No workspaces found in package.json

Diagnose it: reproduce the CI install locally

Install failures are usually environment drift rather than a broken lockfile: a different package-manager major, a different Node version, or a cache that is being restored from a run with different inputs. Reproduce the CI conditions before changing the lockfile, because regenerating it hides the real cause.

Terminal

# match the runner exactly, then install from a clean slate
node --version && npm --version
rm -rf node_modules
npm ci --foreground-scripts

# if that succeeds locally but fails in CI, the difference is the cache
# or the package-manager version, not your lockfile

Common causes

The workspaces glob matches nothing in CI

A "workspaces": ["packages/*"] glob fails if the directory layout in the CI checkout differs, or the package directories lack their own package.json.

A --workspace name that does not match a package name

--workspace/-w takes the package name (or its path). A typo, or naming the directory instead of the package name, yields "workspace not found".

How to fix it

Confirm the workspaces glob and names

List the workspaces npm sees and target by exact package name.

Terminal

npm query .workspace        # list resolved workspaces
# target by the package "name", not the folder:
npm run build -w @acme/api

Verify layout and package manifests

Ensure each matched directory has a valid package.json with a name.
Confirm the workspaces glob matches the checked-out layout.
Use npm install at the root first so workspaces are linked before per-workspace commands.

Verify the fix survives a cold cache

A green run immediately after a fix often proves nothing, because it restored a cache written before the change. Force a cold install once to confirm the fix is real.

.github/workflows/ci.yml

# temporarily bust the cache key to prove the fix on a cold runner
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: package-lock.json
# then bump this suffix once, run, and remove it
#   key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}-v2

How to prevent it

Keep the workspaces glob aligned with the real directory layout.
Target workspaces by package name, not folder name.
Validate the workspace list with npm query .workspace in CI.

Frequently asked questions

What causes npm "No workspaces found" / "workspace not found"?

There are 2 common causes: the workspaces glob matches nothing in ci and a --workspace name that does not match a package name. A "workspaces": ["packages/*"] glob fails if the directory layout in the CI checkout differs, or the package directories lack their own package.json.

How do I fix npm "No workspaces found" / "workspace not found"?

There are 2 fixes depending on which cause you have: confirm the workspaces glob and names and verify layout and package manifests. Work through them in order, since the first is the most common.

What does npm "No workspaces found" / "workspace not found" actually mean?

npm install -w <name> or npm run build -w <name> fails with "No workspaces found" or that the named workspace does not exist.

How do I stop npm "No workspaces found" / "workspace not found" happening again?

Keep the workspaces glob aligned with the real directory layout. The prevention section lists 3 changes that keep it from recurring.