workspace: protocol not supported (npm version) in CI
By Kaveh Alemi·Latchkey
A dependency uses the workspace: protocol (workspace:*, workspace:^) but the package manager or version handling install does not understand it. Older npm and some publish flows reject it.
What this error means
install fails with "Unsupported URL Type \"workspace:\": workspace:*", typically on an npm version that predates workspace protocol support or in a context that resolved before publish.
Diagnose it: which packages does the tool think exist?
Workspace failures are usually a globbing or topology problem: the tool cannot see a package, or it resolved a different dependency graph than you expect.
Terminal
# what the package manager sees
npm query ".workspace" 2>/dev/null || pnpm -r list --depth -1 || yarn workspaces list
# what the task runner will actually build, and in what order
npx turbo run build --dry-run=json | head -40
npx nx graph --file=graph.json
Common causes
npm version too old
The workspace: protocol is supported only in newer npm; older versions reject it.
Published package kept workspace: range
A package published without replacing workspace: ranges leaves consumers unable to install.
Tool does not understand the protocol
A downstream tool resolving dependencies directly does not support workspace:.
How to fix it
Upgrade npm or use pnpm/yarn
Use a package manager and version that supports the workspace protocol.
Terminal
npm install -g npm@latest
npm --version
Replace workspace: ranges on publish
Ensure your publish flow rewrites workspace:* to real versions (pnpm publish does this).
How to prevent it
Pin a package-manager version that supports the workspace protocol in packageManager, and rewrite workspace: ranges at publish time.
Frequently asked questions
What causes workspace: protocol not supported (npm version) in CI?
There are 3 common causes: npm version too old, published package kept workspace: range, and tool does not understand the protocol. The workspace: protocol is supported only in newer npm; older versions reject it.
How do I fix workspace: protocol not supported (npm version) in CI?
There are 2 fixes depending on which cause you have: upgrade npm or use pnpm/yarn and replace workspace: ranges on publish. Work through them in order, since the first is the most common.
What does workspace: protocol not supported (npm version) in CI actually mean?
install fails with "Unsupported URL Type \"workspace:\": workspace:*", typically on an npm version that predates workspace protocol support or in a context that resolved before publish.
How do I stop workspace: protocol not supported (npm version) in CI happening again?
Pin a package-manager version that supports the workspace protocol in packageManager, and rewrite workspace: ranges at publish time.
