How to fix npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names cannot contain spaces in npm

npmBEGINNERMEDIUMUpdated Dec 5, 2025· 167 views

The EINVALIDTAGNAME error with spaces occurs when npm encounters a tag name containing spaces or special characters. This typically happens when using npm tag commands or dist-tags with spaces, or malformed package names.

Quick fix

Fixes npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names cannot contain spaces

# Incorrect:
npm install @ namespace / package --save
npm tag pkg@1.0.0 'my tag'

# Correct:
npm install @namespace/package --save
npm tag pkg@1.0.0 my-tag
  1. Check your command syntax for spaces
  2. Remove spaces from your project folder name
  3. Verify package.json has valid names
  4. Use correct npm dist-tag syntax
npm — error
# Incorrect:
npm install @ namespace / package --save
npm tag pkg@1.0.0 'my tag'
# Correct:
npm install @namespace/package --save
npm tag pkg@1.0.0 my-tag
npm ERR! code EINVALIDTAGNAME
npm ERR! Invalid tag name: tag names cannot contain spaces

What this error means

npm validates distribution tags (dist-tags) and package names using strict rules to ensure compatibility with URL encoding. Any character that would be encoded by JavaScript's encodeURIComponent function—including spaces, special characters like @, ^, >, =, and slashes—triggers this error. npm prevents these invalid tag names to maintain consistency in package distribution and prevent issues with package registry operations. This error is a validation check that npm enforces when creating dist-tags, installing packages with invalid tags, and publishing packages with problematic tag specifications.

Typical symptoms

  • npm install fails with 'EINVALIDTAGNAME: Invalid tag name' error message
  • npm publish command succeeds but npm install fails when trying to use the package
  • Getting error when running npm tag commands with special characters
  • Installation fails after upgrading to a newer npm version
  • Error appears in CI/CD pipelines but works locally or vice versa

Common causes

  1. Using spaces in npm dist-tag names (e.g., 'my tag' instead of 'my-tag')
  2. Including spaces around @ symbol in scoped package names
  3. Package has a dist-tag in package.json with spaces or special characters
  4. Malformed version specifiers or dependency declarations containing spaces
  5. Using literal brackets in package names from copy-pasted examples

How to fix "npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names cannot contain spaces"

1Check your command syntax for spaces

If you're using npm tag or npm install commands, verify there are no spaces around special characters. Spaces around @ in scoped packages are a common cause.

bash
# Incorrect:
npm install @ namespace / package --save
npm tag pkg@1.0.0 'my tag'

# Correct:
npm install @namespace/package --save
npm tag pkg@1.0.0 my-tag

Tag names should use hyphens instead of spaces to separate words.

2Remove spaces from your project folder name

If your project directory contains spaces, it can trigger this error during npm init or npm install. Rename your folder to use hyphens or camelCase.

bash
# Rename from:
cd "My Project"
npm init

# Rename to:
cd my-project
npm init

Use underscores or hyphens instead of spaces in directory names.

3Verify package.json has valid names

Check your package.json file for any malformed package names or dependency version specifiers that contain spaces.

json
// Problematic:
{
  "name": "my package",
  "dependencies": {
    "@scope / pkg": "1.0.0"
  }
}

// Fixed:
{
  "name": "my-package",
  "dependencies": {
    "@scope/pkg": "1.0.0"
  }
}

Package names must be lowercase and can only contain hyphens, underscores, and alphanumeric characters.

4Use correct npm dist-tag syntax

When creating or managing distribution tags, use hyphens instead of spaces. Tag names are case-sensitive and must not contain spaces.

bash
# Incorrect:
npm dist-tag add package@1.0.0 'release candidate'

# Correct:
npm dist-tag add package@1.0.0 rc
npm dist-tag add package@2.0.0 beta

Common valid dist-tags: latest, next, beta, rc, stable, dev

Advanced notes

The EINVALIDTAGNAME error is fundamentally about URL safety. npm uses encodeURIComponent internally when transmitting package metadata to the registry. Characters that encode to special sequences (spaces become %20, @ becomes %40, etc.) can cause parsing issues in the registry. Some older npm versions (pre-v7) were inconsistent—allowing invalid tag creation but failing on installation. Upgrading npm often reveals these hidden issues.

Frequently asked questions

What does "npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names can" mean?
npm validates distribution tags (dist-tags) and package names using strict rules to ensure compatibility with URL encoding. Any character that would be encoded by JavaScript's encodeURIComponent function—including spaces, special characters like @, ^, >, =, and slashes—triggers this error. npm prevents these invalid tag names to maintain consistency in package distribution and prevent issues with package registry operations.
How do I fix "npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names can"?
The EINVALIDTAGNAME error with spaces occurs when npm encounters a tag name containing spaces or special characters. This typically happens when using npm tag commands or dist-tags with spaces, or malformed package names.
What causes "npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names can"?
Using spaces in npm dist-tag names (e.g., 'my tag' instead of 'my-tag') Including spaces around @ symbol in scoped package names Package has a dist-tag in package.json with spaces or special characters
Is the "npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names can" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading