npm "Invalid package name" / "Invalid Version" - Fix a Malformed package.json

By Kaveh Alemi·Latchkey

npm validates the name and version fields of every package.json against strict naming and semver rules. A name with illegal characters, or a version that is not valid semver, makes npm reject the manifest outright.

What this error means

npm aborts immediately with Invalid package name or Invalid Version, naming the offending value. Nothing installs because npm cannot accept the manifest as published or as a workspace.

npm output

npm error code EINVALIDPACKAGENAME
npm error Invalid package name "My_App": name can only contain URL-friendly
npm error characters; name cannot start with an underscore.
# or
npm error Invalid Version: "v1.0"

Diagnose it: reproduce the CI install locally

Install failures are usually environment drift rather than a broken lockfile: a different package-manager major, a different Node version, or a cache that is being restored from a run with different inputs. Reproduce the CI conditions before changing the lockfile, because regenerating it hides the real cause.

Terminal

# match the runner exactly, then install from a clean slate
node --version && npm --version
rm -rf node_modules
npm ci --foreground-scripts

# if that succeeds locally but fails in CI, the difference is the cache
# or the package-manager version, not your lockfile

Common causes

Illegal characters or casing in name

npm names must be lowercase, URL-safe, and cannot start with a dot or underscore. Uppercase letters, spaces, or special characters are rejected.

A version that is not valid semver

A version like v1.0, 1.0, or latest is not valid semver. npm requires a full MAJOR.MINOR.PATCH (optionally with pre-release/build metadata).

How to fix it

Correct the name and version fields

Use a lowercase URL-safe name and a valid semver version.

package.json

// package.json
{
  "name": "my-app",
  "version": "1.0.0"
}

Validate before committing

Run npm pkg get name version to read the current values.
Ensure the name is lowercase, URL-safe, and not prefixed with ./_.
Ensure the version is full semver (1.2.3), not v1.2 or a tag.

Verify the fix survives a cold cache

A green run immediately after a fix often proves nothing, because it restored a cache written before the change. Force a cold install once to confirm the fix is real.

.github/workflows/ci.yml

# temporarily bust the cache key to prove the fix on a cold runner
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: package-lock.json
# then bump this suffix once, run, and remove it
#   key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}-v2

How to prevent it

Keep name lowercase and URL-safe; version full semver.
Use npm version to bump rather than hand-editing.
Lint package.json in CI before installing.

Frequently asked questions

What causes npm "Invalid package name" / "Invalid Version"?

There are 2 common causes: illegal characters or casing in name and a version that is not valid semver. npm names must be lowercase, URL-safe, and cannot start with a dot or underscore.

How do I fix npm "Invalid package name" / "Invalid Version"?

There are 2 fixes depending on which cause you have: correct the name and version fields and validate before committing. Work through them in order, since the first is the most common.

What does npm "Invalid package name" / "Invalid Version" actually mean?

npm aborts immediately with Invalid package name or Invalid Version, naming the offending value.

How do I stop npm "Invalid package name" / "Invalid Version" happening again?

Keep name lowercase and URL-safe; version full semver. The prevention section lists 3 changes that keep it from recurring.