pnpm/yarn "workspace:" Protocol Not Supported in CI

By Kaveh Alemi·Latchkey

A package depends on a sibling via the workspace: protocol (e.g. "@acme/ui": "workspace:*"), but the tool installing it does not understand that protocol. Classically this is npm trying to install a pnpm/yarn workspace, or a published package that leaked an unresolved workspace: spec.

What this error means

Install fails with Unsupported URL Type "workspace:" or a "workspace: protocol not supported" message. It happens when the wrong package manager runs the install, or when a tarball published with workspace: ranges is consumed downstream.

npm output

npm error code EUNSUPPORTEDPROTOCOL
npm error Unsupported URL Type "workspace:": workspace:*

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

Wrong package manager for the workspace

The workspace: protocol is a pnpm/yarn/Bun feature. Running npm install over a repo that uses it (without npm workspaces support for that spec) fails to parse it.

Published package leaked workspace: ranges

When publishing, pnpm/yarn rewrite workspace: to real version ranges. If that rewrite was skipped (wrong publish flow), consumers see an unresolved workspace: spec.

How to fix it

Install with the matching package manager

Use the package manager that understands workspace: and the committed lockfile.

Terminal

pnpm install --frozen-lockfile   # pnpm repos
yarn install --immutable         # yarn berry repos

Publish with proper workspace rewriting

Publish via pnpm publish / yarn npm publish, which rewrite workspace:* to concrete versions.
Never npm publish a package that still contains workspace: ranges.
Pin packageManager so CI and publish use the right tool.

How to prevent it

Use one package manager per repo and pin it via packageManager.
Publish with the tool that rewrites workspace: to real ranges.
Commit the correct lockfile and install with --frozen-lockfile/--immutable.

Frequently asked questions

What causes pnpm/yarn "workspace:" protocol not supported in CI?

There are 2 common causes: wrong package manager for the workspace and published package leaked workspace: ranges. The workspace: protocol is a pnpm/yarn/Bun feature.

How do I fix pnpm/yarn "workspace:" protocol not supported in CI?

There are 2 fixes depending on which cause you have: install with the matching package manager and publish with proper workspace rewriting. Work through them in order, since the first is the most common.

What does pnpm/yarn "workspace:" protocol not supported in CI actually mean?

Install fails with Unsupported URL Type "workspace:" or a "workspace: protocol not supported" message.

How do I stop pnpm/yarn "workspace:" protocol not supported in CI happening again?

Use one package manager per repo and pin it via packageManager. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation