Fix it fast
Most likely: The tag value passed to npm publish --tag or npm dist-tag add looks like a version/range or is in the wrong argument position.
1. Confirm this is your error
Valid dist-tag: latest
Valid dist-tag: canary
Invalid dist-tag: v1.4 # looks like a semver range2. Check the cause
npm view <package> dist-tags --json
npm dist-tag ls <package>
printf '%s\n' "<tag>"3. Apply the safe fix
# Use a non-version-looking tag name.
npm publish --tag beta
# Or update a tag with the explicit argument order.
npm dist-tag add <package>@<version> beta4. Verify it works
npm view <package> dist-tags --json
npm dist-tag ls <package>Don't use unsafe shortcuts
- Do not use tag names like
v1.4,1.x, or1.2.3, npm can confuse them with versions or ranges. - Do not swap the package/version and tag arguments in
npm dist-tag add. - Do not debug registry auth first, this error is usually caused by the tag string itself.
What This Error Means
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.
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.