How to fix npm ERR! code EBADTAR npm ERR! Invalid tarball format in npm

npmINTERMEDIATEMEDIUMUpdated Dec 3, 2025· 143 views

The EBADTAR error indicates npm encountered a corrupted or invalid tarball during package installation. This is typically caused by cache corruption, network issues, or proxy problems.

Quick fix

Fixes npm ERR! code EBADTAR npm ERR! Invalid tarball format

# Remove dependencies and lock file
rm -rf node_modules package-lock.json

# Clear npm cache completely
npm cache clean --force

# Verify cache integrity
npm cache verify

# Reinstall
npm install
  1. Clear npm cache and reinstall
  2. Run verbose install to identify failing package
  3. Check npm and registry configuration
  4. Increase timeout and retry settings
npm — error
# Remove dependencies and lock file
rm -rf node_modules package-lock.json
# Clear npm cache completely
npm cache clean --force
# Verify cache integrity
npm cache verify
# Reinstall
npm install
npm ERR! code EBADTAR
npm ERR! Invalid tarball format

What this error means

This error occurs when npm downloads a package tarball (.tgz file) that's either corrupted, incomplete, or in an unexpected format. The tarball is the compressed archive that contains the package code. Common scenarios include: interrupted downloads leaving partial files in cache, network corruption during transfer, proxy servers re-encoding files incorrectly, or registry issues serving invalid content.

Typical symptoms

  • npm install fails partway through dependency resolution
  • Specific packages fail while others succeed
  • Works on different machine or network
  • Error persists even after retry attempts
  • Related warnings about TAR_ENTRY_INVALID or checksum failure

Common causes

  1. Corrupted npm cache from interrupted downloads
  2. Network corruption during package download
  3. Proxy server intercepting or re-encoding tarballs
  4. Registry serving invalid or incomplete files
  5. Antivirus software modifying downloaded files
  6. Disk I/O errors during extraction

How to fix "npm ERR! code EBADTAR npm ERR! Invalid tarball format"

1Clear npm cache and reinstall

Start with the most effective fix:

bash
# Remove dependencies and lock file
rm -rf node_modules package-lock.json

# Clear npm cache completely
npm cache clean --force

# Verify cache integrity
npm cache verify

# Reinstall
npm install
2Run verbose install to identify failing package

Find exactly which package is corrupted:

bash
npm install --verbose

# Even more detailed
npm install --loglevel=silly

Look for lines like:

bash
npm WARN tar TAR_BAD_ARCHIVE: Unrecognized archive format for package-name@1.0.0
3Check npm and registry configuration

Verify correct registry settings:

bash
# Check registry URL
npm config get registry
# Should be: https://registry.npmjs.org/

# Reset if wrong
npm config set registry https://registry.npmjs.org/

# Check for proxy issues
npm config get proxy
npm config get https-proxy

# Remove proxy if not needed
npm config delete proxy
npm config delete https-proxy
4Increase timeout and retry settings

For slow or unreliable networks, increase tolerances:

Add to ~/.npmrc:

ini
fetch-timeout=60000
fetch-retry-mintimeout=20000
fetch-retry-maxtimeout=120000
fetch-retries=5

Then retry:

bash
npm install
5Check disk space and filesystem

Ensure sufficient disk space:

bash
# Linux/macOS
df -h

# Need at least 1GB free
# If low, clean up:
npm cache clean --force
rm -rf node_modules
6Update npm to latest version

Older npm versions have known tarball handling bugs:

bash
# Update npm
npm install -g npm@latest

# Verify versions
node --version
npm --version

# Reinstall project
rm -rf node_modules package-lock.json
npm install

Advanced notes

For corporate environments with proxies, the proxy may be re-encoding tarballs incorrectly. Check with your IT team if Apache or nginx is configured with AddEncoding directives for .tgz files.

If using a private registry like Verdaccio or Nexus, verify it's properly proxying to npmjs.org. Test with: curl -I https://your-registry/package-name

For persistent issues with specific packages, try installing directly from npm: npm install package-name --registry https://registry.npmjs.org

Frequently asked questions

What does "npm ERR! code EBADTAR npm ERR! Invalid tarball format" mean?
tgz file) that's either corrupted, incomplete, or in an unexpected format. The tarball is the compressed archive that contains the package code. Common scenarios include: interrupted downloads leaving partial files in cache, network corruption during transfer, proxy servers re-encoding files incorrectly, or registry issues serving invalid content.
How do I fix "npm ERR! code EBADTAR npm ERR! Invalid tarball format"?
The EBADTAR error indicates npm encountered a corrupted or invalid tarball during package installation. This is typically caused by cache corruption, network issues, or proxy problems.
What causes "npm ERR! code EBADTAR npm ERR! Invalid tarball format"?
Corrupted npm cache from interrupted downloads Network corruption during package download Proxy server intercepting or re-encoding tarballs
Is the "npm ERR! code EBADTAR npm ERR! Invalid tarball format" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading