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.
This error indicates your npm package is too large for the registry to accept. Different registries have different limits: - npmjs.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.
Check exactly what files will be included:
# 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 *.tgzLook for node_modules/, test/, coverage/, or large files that shouldn't be included.
Whitelist only the files you want to publish:
{
"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
Create .npmignore to exclude files:
# .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.ymlImportant: When .npmignore exists, .gitignore is completely ignored for publishing.
After configuring, verify the package is now smaller:
# 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.
If your package includes compiled/minified code, exclude source maps:
{
"files": [
"dist/index.js",
"dist/index.d.ts"
]
}Or in .npmignore:
*.mapSource maps can be larger than the actual code.
Add a script to check package size before every publish:
{
"scripts": {
"prepublishOnly": "npm pack --dry-run && npm run build"
}
}For automated size monitoring, use size-limit:
npm install --save-dev size-limit @size-limit/file{
"size-limit": [
{
"path": "dist/index.js",
"limit": "100 KB"
}
]
}A real-world example: one developer accidentally published a 324MB package because they didn't have .npmignore and their .gitignore included dist/. Since .gitignore excluded dist/, npm fell back to including everything except .git and node_modules.
Ask yourself for each file: "Does the end user need this to use my package?" Typically publish only: compiled code (dist/, lib/), type definitions (*.d.ts), and essential metadata.
Use npx npm-packlist to see the exact list of files that will be packaged—helpful for debugging complex ignore patterns.
npm ERR! code E401 npm ERR! 401 Unauthorized - Token has expired
Token has expired - npm authentication failure
npm ERR! code ENOAUDIT npm ERR! Audit endpoint not supported
How to fix "npm ERR! code ENOAUDIT - Audit endpoint not supported"
npm ERR! code EBADDEVENGINES npm ERR! devEngines.runtime incompatible with current node version
How to fix "npm ERR! code EBADDEVENGINES - devEngines.runtime incompatible with current node version"
npm ERR! code EAI_NODATA npm ERR! errno EAI_NODATA npm ERR! getaddrinfo EAI_NODATA registry.npmjs.org
How to fix "npm ERR! code EAI_NODATA - getaddrinfo EAI_NODATA"
npm ERR! code ETOOMANYARGS npm ERR! Too many arguments
How to fix "npm ERR! code ETOOMANYARGS - Too many arguments"