Error Knowledge Base npm EINVALIDTAGNAME

npm ERR! code EINVALIDTAGNAME

npm rejected the dist-tag because the tag name is invalid, reserved, or formatted in a way that conflicts with version parsing.

What This Error Means

npm rejected the dist-tag because the tag name is invalid, reserved, or formatted in a way that conflicts with version parsing.

Read this as a precise clue about which part of the workflow broke first. Once you know the failing layer, the fix path gets much shorter.

How to Fix It

The fastest fixes here come from checking the immediate failing layer before you change anything unrelated. Make one correction at a time and re-test from the same environment.

Re-run the command and inspect the exact tag value you passed to npm publish --tag or npm dist-tag add.

Use descriptive tag names like latest, next, beta, or canary instead of version-like strings.

If you meant to install or inspect a tag, list existing tags first:npm view <pkg> dist-tags --json

If you are updating tags, use the explicit form:npm dist-tag add <pkg>@<version> <tag>

Retry after replacing the invalid tag with a non-semver-looking value.

Why It Happens

Usually this comes down to the tag can be interpreted as a semver range, so npm rejects it as ambiguous, the tag starts with a number or v, which often collides with version-style parsing, or the command used the wrong value in the tag position, or the package and tag arguments were swapped.

Verify the Fix

Run npm view <pkg> dist-tags --json and confirm the intended tag exists with the expected version, and repeat the original npm dist-tag or npm publish --tag command and confirm EINVALIDTAGNAME is gone.

Check the exact command and local inputs

Check the literal tag value before retrying. If it looks like v1.4 or 1.x, rename it.

List current tags with npm view <pkg> dist-tags --json so you can compare against a known-good tag.

If the error happened in CI, print the resolved tag variable before running npm.

Examples

Valid dist-tag: latest
Valid dist-tag: canary
Invalid dist-tag: v1.4  # looks like a semver range
npm dist-tag add @acme/widget@1.4.0 beta

How npm validates the command before it runs

This is the part worth understanding if the quick fix did not hold. It explains what npm is trying to do at the moment the error appears.

Dist-tags share the same namespace slot as versions when you use npm install <pkg>@<specifier>.

npm rejects tag names that look like semver ranges because they would be ambiguous during resolution. This is usually a local command or input problem, not a registry availability problem.

Prevent It From Coming Back

To prevent this, avoid tags that look like versions or semver ranges, standardize on a small set of release tags such as latest, next, beta, and canary, and document the exact npm dist-tag add <pkg>@<version> <tag> command used in release automation.

Need help or found a mistake? Contact RepoFlow support for questions.

Join our mailing list