How to fix npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size in npm

Q: What does "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed" mean?

This error indicates your npm package is too large for the registry to accept. com: No explicit documented limit, but practical issues arise above 50MB - AWS CodeArtifact: 2 GB maximum - Azure Artifacts: 500 MB per package file - Private Verdaccio: Often defaults to 2 MB The most common cause is accidentally including files that shouldn't be published, like node_modules, test directories, or large assets.

Q: What causes "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed"?

node_modules accidentally included in package Missing .npmignore file (falls back to .gitignore rules) Test directories and fixtures included

Q: Is the "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed" error serious?

It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

npmINTERMEDIATELOWLast verified Dec 3, 2025· 32 views

The ETOOLARGE error occurs when publishing an npm package that exceeds size limits. This usually happens when node_modules, test files, or large assets are accidentally included in the published package.

Quick fix

Fixes npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size

# Preview files without publishing
npm pack --dry-run

# Create tarball locally to inspect
npm pack

# List tarball contents
tar -tzf my-package-1.0.0.tgz | head -50

# Check tarball size
ls -lh *.tgz

Diagnose what's being published
Use the files field in package.json (recommended)
Create .npmignore file (alternative approach)
Verify package contents

How to fix "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size"

1Diagnose what's being published

Check exactly what files will be included:

bash

# Preview files without publishing
npm pack --dry-run

# Create tarball locally to inspect
npm pack

# List tarball contents
tar -tzf my-package-1.0.0.tgz | head -50

# Check tarball size
ls -lh *.tgz

Look for node_modules/, test/, coverage/, or large files that shouldn't be included.

2Use the files field in package.json (recommended)

Whitelist only the files you want to publish:

json

{
  "name": "my-package",
  "version": "1.0.0",
  "files": [
    "dist/",
    "lib/",
    "index.js"
  ]
}

This is the safest approach—only explicitly listed files are published.

Automatically included (no need to list):
- package.json
- README (any case)
- LICENSE/LICENCE
- CHANGELOG

3Create .npmignore file (alternative approach)

Create .npmignore to exclude files:

bash

# .npmignore

# Version control
.git
.gitignore

# Dependencies (auto-ignored but explicit)
node_modules/

# Testing
test/
__tests__/
*.test.js
coverage/

# Development
.env
.vscode/
tsconfig.json
webpack.config.js

# Source maps
*.map

# CI/CD
.github/
.travis.yml

Important: When .npmignore exists, .gitignore is completely ignored for publishing.

4Verify package contents

After configuring, verify the package is now smaller:

bash

# Create tarball
npm pack

# Check file count
tar -tzf *.tgz | wc -l

# Check size
ls -lh *.tgz

# Extract and inspect
tar -xzf *.tgz
ls -la package/

A typical library should be under 1MB packed.

5Exclude source maps if building

If your package includes compiled/minified code, exclude source maps:

json

{
  "files": [
    "dist/index.js",
    "dist/index.d.ts"
  ]
}

Or in .npmignore:

bash

*.map

Source maps can be larger than the actual code.

6Use prepublishOnly to verify size

Add a script to check package size before every publish:

json

{
  "scripts": {
    "prepublishOnly": "npm pack --dry-run && npm run build"
  }
}

For automated size monitoring, use size-limit:

bash

npm install --save-dev size-limit @size-limit/file

json

{
  "size-limit": [
    {
      "path": "dist/index.js",
      "limit": "100 KB"
    }
  ]
}

How to fix npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size in npm

Quick fix

What this error means

Typical symptoms

Common causes