How to fix npm ERR! Invalid name: name cannot contain special characters in npm

npmBEGINNERLOWUpdated Dec 5, 2025· 144 views

This error occurs when your package name contains characters not allowed by npm. Package names must be lowercase, URL-friendly, and follow specific naming rules.

Quick fix

Fixes npm ERR! Invalid name: name cannot contain special characters

❌ Invalid: "My-Cool-Package"
✅ Valid:   "my-cool-package"

❌ Invalid: "my package"
✅ Valid:   "my-package"

❌ Invalid: "my@package"
✅ Valid:   "my-package"

❌ Invalid: ".my-package"
✅ Valid:   "my-package"
  1. Use only allowed characters
  2. Fix package.json name field
  3. Rename your project folder
  4. Use scoped packages for organization names
npm — error
❌ Invalid: "My-Cool-Package"
✅ Valid:   "my-cool-package"
❌ Invalid: "my package"
✅ Valid:   "my-package"
❌ Invalid: "my@package"
✅ Valid:   "my-package"
❌ Invalid: ".my-package"
✅ Valid:   "my-package"
npm ERR! Invalid name: name cannot contain special characters

What this error means

npm enforces strict naming rules for packages to ensure they work correctly across different systems and can be used in URLs. When you run `npm init` or have an invalid name in package.json, npm rejects names that don't follow these rules. Package names must: - Be lowercase only - Not contain spaces - Not start with a dot (.) or underscore (_) - Not contain special characters like @, #, $, %, &, *, etc. (except in scoped packages) - Be URL-friendly - Be 214 characters or less

Typical symptoms

  • npm init fails with 'Invalid name' error
  • npm install fails due to invalid package.json name
  • Error mentions special characters or URL-friendly
  • Publishing to npm registry fails

Common causes

  1. Package name contains uppercase letters
  2. Package name contains spaces
  3. Package name starts with dot or underscore
  4. Package name contains special characters (@#$%&*)
  5. Package name matches Node.js core module
  6. Package name is an npm reserved word

How to fix "npm ERR! Invalid name: name cannot contain special characters"

1Use only allowed characters

Valid package names can only contain:
- Lowercase letters (a-z)
- Numbers (0-9)
- Hyphens (-)
- Underscores (_) - but not at the start
- Dots (.) - but not at the start

Examples:

bash
❌ Invalid: "My-Cool-Package"
✅ Valid:   "my-cool-package"

❌ Invalid: "my package"
✅ Valid:   "my-package"

❌ Invalid: "my@package"
✅ Valid:   "my-package"

❌ Invalid: ".my-package"
✅ Valid:   "my-package"
2Fix package.json name field

Edit your package.json:

json
{
  "name": "my-valid-package-name",
  "version": "1.0.0"
}

Convert your name:
- Replace spaces with hyphens
- Convert to lowercase
- Remove special characters

3Rename your project folder

If you're using npm init and it's using your folder name:

bash
# Rename folder to valid name
mv "My Project" my-project
cd my-project
npm init -y
4Use scoped packages for organization names

For organization or personal namespaces, use scoped packages:

json
{
  "name": "@mycompany/my-package"
}

Scoped names follow the format @scope/package-name where both parts must follow naming rules.

Advanced notes

Reserved names: npm blocks certain names:
- Node.js core modules: fs, http, path, etc.
- npm commands: install, publish, test, etc.
- Previously unpublished names that were squatted

Name validation: Use the validate-npm-package-name package to check names:

bash
npx validate-npm-package-name "your-package-name"

Legacy names: Some very old packages have names that wouldn't be valid today (with capitals or special chars). New packages must follow current rules.

Private packages: Even if you never publish, follow naming conventions. Invalid names can cause issues with tools and scripts that parse package.json.

Frequently asked questions

What does "npm ERR! Invalid name: name cannot contain special characters" mean?
npm enforces strict naming rules for packages to ensure they work correctly across different systems and can be used in URLs. json, npm rejects names that don't follow these rules. ) or underscore (_) - Not contain special characters like @, #, $, %, &, *, etc.
How do I fix "npm ERR! Invalid name: name cannot contain special characters"?
This error occurs when your package name contains characters not allowed by npm. Package names must be lowercase, URL-friendly, and follow specific naming rules.
What causes "npm ERR! Invalid name: name cannot contain special characters"?
Package name contains uppercase letters Package name contains spaces Package name starts with dot or underscore
Is the "npm ERR! Invalid name: name cannot contain special characters" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading