Skip to content

How to Fix npm publish Failed Errors

DodaTech 2 min read

In this tutorial, you'll learn about How to Fix npm publish Failed Errors. We cover key concepts, practical examples, and best practices.

The Problem

npm publish fails with errors such as 403 Forbidden, unregistered user, You cannot publish over the previously published version, or Package name too similar to existing package, preventing your package from being published to the registry.

Quick Fix

Step 1: Verify you are logged in

Check your npm login status:

npm whoami

If this returns a username, you are logged in. If it errors:

npm login
Username: your-username
Password:
Email: (this IS public) you@example.com

Step 2: Bump the version

You cannot publish a version that already exists. Check the current version:

npm version
{ 'my-package': '1.0.0' }

Bump it with npm version:

npm version patch
v1.0.1

Step 3: Check if the package name is taken

Search the registry for your package name:

npm search my-package-name

If the name exists, rename it in package.json:

node -e "const p = require('./package.json'); p.name = '@your-scope/my-package'; console.log(JSON.stringify(p, null, 2));"

Step 4: Configure .npmignore

Exclude unnecessary files from the published package:

echo -e "node_modules\nsrc\n.git\n*.map\n.DS_Store\ntest" > .npmignore

Verify what will be published:

npm pack --dry-run
my-package-1.0.1.tgz
package.json
README.md
dist/index.js

Step 5: Use scoped packages for private packages

Publish a private scoped package:

npm publish --access public

Scoped packages are free for public use and avoid naming collisions.

Alternative Solutions

Use np for streamlined publishing

The np package handles version bumps, git tags, and publishing:

npx np

Use GitHub Actions for automated publishing

Publish automatically on tag pushes:

# .github/workflows/publish.yml
on:
  push:
tags:
      - 'v*'
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Common Mistakes to Avoid

Forgetting to log in before publishing. npm publish requires authentication. Run npm login first or configure NPM_TOKEN in CI.

Not updating the version number. The registry rejects duplicate versions. Use npm version patch before each publish.

Publishing sensitive files. Files like .env, node_modules, or secrets.json can be accidentally published. Always use .npmignore.

Pro Tips

Use npm version with pre-release tags. For testing, use npm version prerelease --preid=beta which creates version 1.0.1-beta.0 and publishes with npm publish --tag beta.

Use npm pack to inspect the tarball. Run npm pack and extract the resulting .tgz file to see exactly what files will be published.

Use .npmignore or the files field. Either create .npmignore or use the files array in package.json to whitelist what gets published.

Prevention

  • Run npm whoami and npm pack --dry-run before every publish.
  • Use npm version patch to auto-increment after each release.
  • Always add .npmignore or use files in package.json to control what gets published.

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro