npm --workspace Filter Matched No Packages - Fix Monorepo Targeting in CI

The --workspace/-w filter selects a workspace by its package name or its path. A command that names something the filter cannot resolve runs against nothing - npm reports no matching workspace, and the build/test you expected never executes.

What this error means

npm run build -w <target> or npm <cmd> --workspace=<target> completes without running in any package, or errors that no workspace matched. The target is a folder name, a typo, or a package excluded by the workspaces globs.

$ npm run test -w api
npm error No workspaces found:
npm error   --workspace=api
# the package name is "@acme/api", not the folder "api"

Common causes

Filtering by folder name, not package name

-w matches the workspace name field (or a path). Passing the directory name when it differs from the package name resolves to no workspace.

The workspace is not covered by the workspaces globs

A package outside the root workspaces patterns is not a known workspace, so the filter cannot select it.

How to fix it

Target by the exact package name or path

List the resolved workspaces, then filter by the name npm knows.

npm query .workspace          # list workspaces npm sees
# filter by package name:
npm run test -w @acme/api
# or by path:
npm run test --workspace=packages/api

Confirm the workspaces globs

1. Ensure the target directory is matched by the root workspaces patterns.
2. Verify each workspace has a package.json with a name.
3. Use --workspaces (plural) to run across all, or -w <name> for one.

How to prevent it

• Filter workspaces by package name or path, not folder label.
• Keep the workspaces globs covering every package.
• List workspaces with npm query .workspace before scripting filters.

Related guides