Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install fails with EUNSUPPORTEDPROTOCOL

Errornpm ERR! code EUNSUPPORTEDPROTOCOL

Short answer

npm raises EUNSUPPORTEDPROTOCOL when a dependency in package.json uses a spec form npm does not know. The usual one is workspace:, which Yarn and pnpm define but npm's documented forms do not include. Replace it with a version range of the workspace name, or install with the tool the repo was made for.

  • Applies to npm 10, npm 11, Node.js 22, pnpm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find the dependency value that is not a version range, URL, file: path or git form.

    grep -nE '"[^"]+": "[a-z]+:' package.json */package.json packages/*/package.json
  2. 2Match what you see, then jump to its fix

    1. 1A value such as "workspace:*" in a dependencies blockA workspace: dependency installed with npmFix
    2. 2A dependency such as a tarball link or repo address that has no protocol, or a made-up prefixA URL or path spec is not in a documented formFix

What does the error look like?

  • npm ERR! code EUNSUPPORTEDPROTOCOL
  • npm error code EUNSUPPORTEDPROTOCOL

Cause 1 of 2

A workspace: dependency installed with npm

1Check

The workspace: prefix is a Yarn and pnpm protocol for linking monorepo packages. npm's package.json docs list versions, tarballs, git URLs, file: paths and aliases, and npm's workspaces docs link packages by their name.

grep -rn "workspace:" --include=package.json . | grep -v node_modules
ls pnpm-workspace.yaml yarn.lock .yarnrc.yml 2>/dev/null

2Fix

If the repo uses pnpm or Yarn (look for pnpm-workspace.yaml or yarn.lock), install with that tool. If it should be an npm monorepo, list the folders under workspaces in the root package.json and replace each workspace: value with a version range of that package's name.

// root package.json
{ "workspaces": ["packages/*"] }

// a package that needs another one
"dependencies": { "@acme/shared": "^1.0.0" }

3Verify

Run the install from the repo root.

npm install

Confirmed by pnpm.io

Did this fix it?

Cause 2 of 2

A URL or path spec is not in a documented form

1Check

npm install accepts a tarball URL only when it begins with the protocol, a git remote with git, git+ssh, git+http, git+https or git+file, and local folders and tarballs by path.

grep -nE '"(git|http|https|file|github)[^"]*"' package.json

2Fix

Write the dependency in one of the documented forms.

"dependencies": {
  "tool-a": "https://example.com/tool-a-1.0.0.tgz",
  "tool-b": "github:owner/repo#v1.0.0",
  "tool-c": "file:../tool-c"
}

3Verify

Run the install again.

npm install

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Pick one package manager per repo and write it in the README, and commit only its lockfile.
  • Run the install command from the repo root, not inside a package folder.
  • Keep non-registry dependencies in the documented forms.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.