How to fix npm ERR! 413 Payload Too Large in npm

npmBEGINNERMEDIUMUpdated Dec 6, 2025· 228 views

The HTTP 413 Payload Too Large error occurs when your npm package exceeds size limits. This can be caused by accidentally including build artifacts, dependencies, or large assets in your package.

Quick fix

Fixes npm ERR! 413 Payload Too Large

# Create the tarball without publishing
npm pack

# Check the size
ls -lh *.tgz

# List contents
tar -tzf your-package-1.0.0.tgz
  1. Check package size and contents
  2. Create or update .npmignore
  3. Use files field in package.json
  4. Check for accidental inclusions
npm — error
# Create the tarball without publishing
npm pack
# Check the size
ls -lh *.tgz
# List contents
tar -tzf your-package-1.0.0.tgz
npm ERR! 413 Payload Too Large

What this error means

This error indicates that the package you're trying to publish is larger than the registry allows. npm has size limits to prevent accidental publishing of enormous packages that would impact download times and storage. The current npm registry limit is around 260MB compressed, but you should aim much smaller. Large packages usually indicate accidentally included files like node_modules, dist folders, or large assets.

Typical symptoms

  • npm publish fails with 413 error
  • Package file is unexpectedly large
  • Publishing times out before error
  • npm pack creates very large tarball
  • node_modules accidentally included
  • Large assets bundled in package

Common causes

  1. node_modules included in package
  2. Missing or incorrect .npmignore file
  3. .git directory included
  4. Build artifacts included (dist/, build/)
  5. Large binary files or assets
  6. Test fixtures and mock data
  7. Documentation with large images

How to fix "npm ERR! 413 Payload Too Large"

1Check package size and contents

Preview what will be published:

bash
# Create the tarball without publishing
npm pack

# Check the size
ls -lh *.tgz

# List contents
tar -tzf your-package-1.0.0.tgz

Look for unexpected files.

2Create or update .npmignore

Exclude unnecessary files:

bash
# .npmignore
node_modules/
.git/
src/           # if distributing compiled only
test/
tests/
__tests__/
coverage/
.nyc_output/
*.log
.env*
.DS_Store
*.tgz
docs/
examples/
3Use files field in package.json

Whitelist specific files instead:

json
{
  "name": "your-package",
  "files": [
    "dist",
    "lib",
    "README.md"
  ]
}

This is more explicit than .npmignore.

4Check for accidental inclusions

Common culprits:

bash
# Check for large files
find . -type f -size +1M -not -path "./node_modules/*"

# Check for sensitive files
tar -tzf *.tgz | grep -E "\.env|secret|credential"
5Move large assets to CDN

For packages with large static files:

1. Host images/videos on CDN
2. Reference by URL in code
3. Use postinstall script to download if needed:

json
{
  "scripts": {
    "postinstall": "node download-assets.js"
  }
}
6Split into multiple packages

For legitimately large packages:

bash
# Create separate packages
my-package          # Core functionality
my-package-assets   # Optional large assets
my-package-cli      # CLI tools

Users install only what they need.

Advanced notes

Use npm pack --dry-run to see what would be included without creating a file. The files field in package.json is generally safer than .npmignore as it's a whitelist. For packages with native binaries, consider using prebuild or node-pre-gyp to distribute prebuilt binaries separately. Large packages increase install times for all users, impacting CI/CD pipelines.

Frequently asked questions

What does "npm ERR! 413 Payload Too Large" mean?
This error indicates that the package you're trying to publish is larger than the registry allows. npm has size limits to prevent accidental publishing of enormous packages that would impact download times and storage. The current npm registry limit is around 260MB compressed, but you should aim much smaller.
How do I fix "npm ERR! 413 Payload Too Large"?
The HTTP 413 Payload Too Large error occurs when your npm package exceeds size limits. This can be caused by accidentally including build artifacts, dependencies, or large assets in your package.
What causes "npm ERR! 413 Payload Too Large"?
node_modules included in package Missing or incorrect .npmignore file .git directory included
Is the "npm ERR! 413 Payload Too Large" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading