Fixed - npm err code einvalidpackagename

npm ERR! code EINVALIDPACKAGENAME error can be frustrating. Discover common reasons why this happens, including invalid characters, reserved names, and formatting errors

Jun 27, 2023 | Read time 6 minutes

🔔 Table of contents

Introduction

If you are working with NPM and came across this error: “npm ERR! code EINVALIDPACKAGENAME” - this would mean that your package name in your package.json file is not valid and will need to be fixed.

This error came up for me when I was just doing a npm update -g - updating all of my npm packages globally and then I came across this error.

npm ERR! code EINVALIDPACKAGENAME
npm ERR! Invalid package name ".bin": name cannot start with a period

Another reason why this error comes up is that the package name value in the package.json is not valid:

For example if we see below:

{
  "name": "My-Cool_Package@2023", 
  "version": "1.0.0",
  "description": "A sample package",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {}
}

We can see that this package.json file, the package name “My-Cool_Package@2023” is invalid because it contains uppercase letters and special characters (@). According to npm package naming rules, package names must be lowercase, and can only contain hyphens (-), underscores (), and alphanumeric characters. They can’t start with a dot (.) or an underscore (), and they can’t contain any non-URL-safe characters.

Issues with your environment

If the issue is outside of your control and from you just updating npm update, then we can look into some fixes:

  • Make sure to clear NPM cache
  • Delete the folder in node_modules directory.

Delete the node_modules folder

I was getting the error:

D:\SashaDebugging>npm update -g
npm ERR! code EINVALIDPACKAGENAME
npm ERR! Invalid package name ".corepack-yRBjKBW1" of package ".corepack-yRBjKBW1@*": name cannot start with a period.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\SashaChernykh\AppData\Local\npm-cache\_logs\2023-02-04T06_33_17_981Z-debug-0.log

I deleted the folder:

C:\Program Files\nodejs\node_modules\.corepack-yRBjKBW1

Now I can successfully update my npm packages:

npm update -g

added 180 packages, removed 236 packages, and changed 2338 packages in 36m

369 packages are looking for funding
  run `npm fund` for details

Clean NPM cache

npm cache clean --force

When NPM installs modules, it keeps a cache of the downloaded files. This will be ~/.npm on Posix, or %AppData%/npm-cache on Windows.

So when the next time you try to install the same package and its dependencies, it will go to the cache folder and not waste time downloading it again.

NPM cache is usually advertised as “self healing”, however I have found that I need to run this a few times!

Issues with the package.json file

If the issue is due is in your control and you can make the change to the package.json, then consider the following:

  • Illegal characters
  • Package name length
  • Reserved Names
  • Scoped naming
  • Urls
  • Invalid JSON

Illegal characters

Illegal characters: Package names must not have spaces, and can only contain lowercase letters, hyphens (-), underscores (), and numbers. They also must not start with a dot (.) or an underscore ().

Too long

Package names should be reasonably short, with a recommended maximum of 214 characters.

Reserved Names

Some package names are reserved for official use by npm. You cannot use names that are already taken, start with “npm”, or have names similar to existing npm commands.

Here are some general rules:

Core Node.js Modules: Package names that match Node.js core modules, such as http, fs, path, querystring, stream, url, util, and so on, are reserved. You can find the full list of core Node.js modules in the Node.js documentation.

NPM Commands: Names that match npm CLI commands, such as install, publish, test, start, stop, link, prune, help, init, uninstall, update, and so on, are also reserved.

Names Starting with “npm”: Names that start with npm (such as npm-package, npm-module, etc.) are reserved for official npm packages.

Existing Packages: Any package name that’s already been used on the npm registry is reserved by the person or organization that first used it.

Scoped package naming error

If you’re using scoped packages (like @username/package), ensure you’ve followed the correct naming convention.

Here’s an example of a correctly named scoped package:

{
  "name": "@username/my-package",
  "version": "1.0.0"
}

The @username is the scope, and my-package is the package name. The scope is usually a username or an organization name. This helps avoid naming conflicts between different packages.

An incorrect or invalid scoped package name might look like this:

{
  "name": "@username/My-Package", // Capital letters are not allowed.
  "version": "1.0.0"
}

or

{
  "name": "@username/my package", // Spaces are not allowed.
  "version": "1.0.0"
}

or

{
  "name": "@username/.my-package", // Package name cannot start with a dot.
  "version": "1.0.0"
}

or

{
  "name": "@username/_my-package", // Package name cannot start with an underscore.
  "version": "1.0.0"
}

All these examples will result in an EINVALIDPACKAGENAME error because they contain uppercase letters, spaces, or begin with dots or underscores. To fix the issue, ensure your package name conforms to the npm package naming rules:

It must be all lowercase. No spaces. Cannot start with a dot or an underscore. Use only alphanumeric, underscore, or hyphen characters.

URLs

Package names can’t look like URLs, e.g., containing . and /.

npm ERR! code EINVALIDPACKAGENAME
npm ERR! Invalid package name "Authorization Error" of package "Authorization Error@*": 
   name can only contain URL-friendly characters.

Incorrectly formatted JSON

This could also be due to JSON formatting issues in your package.json file.

Summary

👋 About the Author

G'day! I am Kentaro a software engineer based in Australia. I have been creating design-centered software for the last 10 years both professionally and as a passion.

My aim to share what I have learnt with you! (and to help me remember 😅)

Follow along on Twitter , GitHub and YouTube

About

Hi, I'm Kentaro - a sofware engineer sharing my programming tips!