npm "Unsupported URL Type 'workspace:'" - Fix workspace: Protocol Deps

A dependency is specified with the workspace: protocol (e.g. "@app/lib": "workspace:*"), which pnpm and Yarn understand but older npm does not. npm rejects it as an unsupported URL type.

What this error means

npm install fails with Unsupported URL Type "workspace:" pointing at a dependency in a monorepo package. The same repo installs fine under pnpm or Yarn, which natively support the protocol.

npm error Unsupported URL Type "workspace:": workspace:*
npm error     at unsupportedURLType (.../npm/node_modules/npm-package-arg/...)

Common causes

Using the workspace: protocol with an npm that lacks support

The workspace: protocol originated with pnpm/Yarn. Older npm releases do not parse it and abort. The repo is configured for a different package manager.

Wrong package manager in CI

CI runs npm install against a repo whose workspaces use workspace: ranges - the wrong tool for that lockfile and manifest.

How to fix it

Use the package manager the repo is built for

If the manifests use workspace:, install with pnpm or Yarn (whichever owns the lockfile), pinned via Corepack.

corepack enable
# use the manager the repo declares
pnpm install   # or: yarn install

Use a recent npm if you must stay on npm

Modern npm supports workspace: in workspace ranges. Upgrade npm, and ensure the repo’s workspaces are configured for npm.

npm install -g npm@latest
npm --version   # confirm a version that supports workspace:

How to prevent it

• Pin the package manager with the packageManager field and Corepack.
• Run CI with the same manager that owns the lockfile.
• Keep npm current if your workspaces rely on the workspace: protocol.

Related guides