Fixed - npm err code eunsupportedprotocol

Introduction

The error “npm ERR! code EUNSUPPORTEDPROTOCOL” suggests that npm has encountered an unsupported protocol, often when trying to download a package.

The reason for this can be that you have issues with your package.json, you are using a older version of Node or that your NPM cache needs to be cleared.

SO this happened to me when I tried to install the Gatsby starter kit.

After downloading it and running npm install, I received the following error:

A more detailed error looks like this:

info Creating new site from git:
https://github.com/Vagr9K/gatsby-advanced-starter.git

Cloning into 'YourProjectName2'...
remote: Enumerating objects: 420, done.
remote: Counting objects: 100% (420/420), done.
remote: Compressing objects: 100% (373/373), done.
remote: Total 420 (delta 44), reused 268 (delta 22), pack-reused 0
Receiving objects: 100% (420/420), 7.74 MiB | 11.79 MiB/s, done.
success Created starter directory layout
info Installing packages...

npm ERR! code EUNSUPPORTEDPROTOCOL
npm ERR! Unsupported URL Type "workspace:": workspace:*

npm ERR! A complete log of this run can be found in:

 ERROR

Command failed with exit code 1: npm install

We can troubleshoot this error by doing the following:

• Check if the protocol is supported by NPM
• Upgrade to the latest NPM
• Consider using yarn

Check if the protocol is supported by NPM

From my previous example, I found that I got the error:

npm ERR! Unsupported URL Type "workspace:": workspace:*

The package.json might look something like this:

{
  "name": "my-project",
  "version": "0.0.0",
  "devDependencies": {
    "@babel/core": "7.18.0",
    "@babel/eslint-parser": "7.18.2",
    ...
    ...
    "@next/bundle-analyzer": "workspace:*",
    "@next/env": "workspace:*",
    "@next/eslint-plugin-next": "workspace:*",
    ...

After a bit of digging around, as of writing, the workspace: protocol is not supported by NPM, but a more PNPM thing.

So to fix this and get to build the project, I had to setup PNPM.

What is PNPM exactly?

PNPM (pronounced “pin-pm”) is a package manager for JavaScript projects. It stands for “Fast, disk space efficient package manager.” PNPM is designed as an alternative to other popular package managers like npm (Node Package Manager) and Yarn.

To start using PNPM, you need to install it globally on your system using npm or another package manager. Once installed, you can create a new project and initialize it with PNPM by running the appropriate commands. PNPM provides commands similar to npm and Yarn for installing, updating, and managing dependencies.

Generally, NPM will have the following rules when it comes to protocols that it supports:

• IF there is no protocol prefix, NPM will go to the NPM registry to download the package.

{
  "name": "my-project",
  "version": "0.0.0",
  "devDependencies": {
    "@babel/core": "7.18.0",
    ...

For example, in the above - NPM will get "@babel/core": "7.18.0" from the NPM registry.

• The file: protocol. This protocol allows you to specify a local package dependency using a file path. It is useful when working with packages that are not published on the npm registry yet.

For example:

    "my-package": "file:../location-of-your-package"

• The git: protocol tells NPM to take it from a Git repository. We can provide the Git repository URL along with a specific commit, branch, or tag. For example: “my-package”:

"git+https://github.com/user/repo.git#v1.0.0"

• GitHub protocol (github:) - Shorthand for specifying package dependencies hosted on GitHub. It simplifies the process by requiring only the repository user and name. For example: “my-package”: “github:user/repo”

• HTTP/HTTPS protocol (http: or https:) - You can specify a package dependency available through HTTP or HTTPS URLs. For example: "my-package": "https://example.com/my-package"

The workspace protocol in PNPM

By default, when you use PNPM, it tries to link packages from your project’s workspace (a collection of related packages) if they match the specified version requirements. For example, if Package A requires Package B version 1.0.0, and Package B version 1.0.0 is present in the workspace, PNPM will link to it.

However, things can get a bit uncertain when the required package version isn’t available in the workspace. In such cases, PNPM might download the package from an external source, like the internet, which introduces some unpredictability.

To address this, PNPM introduced the workspace protocol. When you use the workspace protocol, you’re telling PNPM to only use packages that exist within the workspace.

If a package version specified with the workspace protocol is missing, PNPM won’t download it from an external source, and the installation will fail.

This protocol ensures that only local packages from the workspace are used, giving you more control and predictability.

The workspace protocol is especially useful when you disable the option to link packages from external sources.

In that case, PNPM will only link packages from the workspace if you explicitly specify the workspace protocol in your project’s dependencies.

In simpler terms, the workspace protocol in PNPM helps you ensure that your project only uses packages from your local workspace and prevents unexpected installations from external sources.

Tip: Make sure the package is accessible

If you are using a custom package URL to NPM, the obvious thing to make sure is that the package can be accessed.

So I would make sure that I can access the link from a browser!

The Link protocol

In some instances, I have tried to use the “link:” protocol to point to a local package that I have developed.

The problem is that I get the following EUNSUPPORTEDPROTOCOL error aswell.

$ npm install
npm ERR! code EUNSUPPORTEDPROTOCOL
npm ERR! Unsupported URL Type "link:": link:../some-other-module/node_modules/react

To fix this issue we need to use the “file:” protocol instead of “link:”

The updated package.json might look like this:

...
"dependencies": {
  ...
  "react": "file:../some-other-module/node_modules/react",
}

Update NPM

Update npm and Node.js: If none of the above solutions work, you might want to consider updating npm and Node.js to the latest versions, as the issue could be a bug that’s been fixed in a more recent version.

// Command I run to install this package
npm i @microsoft/microsoft-graph-client@1.7.2-spfx

// Error
npm ERR! code EUNSUPPORTEDPROTOCOL
npm ERR! Unsupported URL Type "npm:": npm:@microsoft/microsoft-graph-client@1.7.2-spfx

The above error was caused by me having a older version of NPM (version 4).

With newer versions, the “NPM:" protocol is supported!

We can upgrade NPM to the latest version by doing:

npm install npm@latest -g

Consider using Yarn

Another option going forward is to move over to use Yarn instead of NPM.

It has similar functionalities to npm, but I find it can be more reliable in certain situations.

You can install Yarn globally using npm with this command:

npm install -g yarn

Once Yarn is installed, you can use it to install your project dependencies. Instead of using npm install, you would use yarn install. Yarn reads from the same package.json file as npm, so it will install the same dependencies.

Before switching to Yarn, remember to delete the node_modules folder and package-lock.json file (if they exist) from your project directory, as these are specific to npm and could cause conflicts. Yarn will generate its own versions of these when you run yarn install.

Also, remember that switching package managers can have implications for your project and your team if you are working with others. Make sure everyone is aware of the change and is comfortable with using Yarn.

In case you face issues with Yarn or decide to switch back to npm later, you can uninstall Yarn using npm:

npm uninstall -g yarn

Summary

In this post I went over the EUNSUPPORTEDPROTOCOL error when running NPM install.

This error is caused by NPM not recognizing the protocol that we are using in our package.json file to manage dependencies.

NPM just supports protocols such as http/https, file:, git:, github: and npm:. Anything outside of this will give the EUNSUPPORTEDPROTOCOL error.

References

• https://pnpm.io/workspaces#workspace-protocol-workspace