The npm EPIPE error occurs when npm tries to write data to a pipe or stream that has been closed. This typically happens due to network issues, Node.js version bugs, or stream mismatches during package installation.
The "EPIPE" error in npm stands for "Error: Pipe" and is a POSIX error code indicating a broken pipe or socket connection. This error occurs when npm attempts to write data to a stream or pipe that no longer has a process reading from it. When you run `npm install` or `npm ci`, npm communicates with the npm registry over the network and processes data through various internal streams. If any of these connections are unexpectedly closed—whether due to network instability, process termination, or bugs in Node.js itself—npm cannot complete its write operation, resulting in the EPIPE error. This error became particularly common in October 2022 when Node.js v16.18.0 introduced a breaking change that affected npm in CI/CD environments. The error can also occur due to memory leaks in Node applications, corporate proxy issues, or when the npm registry connection is interrupted.
Since EPIPE errors are often intermittent due to network issues, a simple retry may succeed:
# Wait a moment and retry
npm install
# Or with npm ci for clean installs
npm ciIf the error persists across multiple attempts, proceed to the other solutions.
A corrupted cache can cause stream processing issues. Clear it and retry:
# Clear the npm cache forcefully
npm cache clean --force
# Verify the cache is cleared
npm cache verify
# Now retry installation
npm installThis removes all cached packages and metadata, forcing npm to download fresh data.
Certain Node.js versions, particularly v16.18.0, introduced bugs that cause EPIPE errors:
# Check your current Node.js version
node --version
# If using v16.18.0, downgrade or upgrade
nvm install 16.17.1
nvm use 16.17.1
# Or upgrade to a newer patched version
nvm install 18
nvm use 18If you're using Docker, update your base image:
# Instead of node:latest or node:16
FROM node:18-alpine
# Or pin to a known working version
FROM node:16.17.1-busterThe audit step can trigger EPIPE errors in some environments. Bypass it:
# Skip the audit during installation
npm ci --no-audit
# Or for regular install
npm install --no-auditNote: This skips security vulnerability checks, so use it only as a workaround and consider running npm audit separately afterward.
Network issues, especially behind corporate proxies, can cause EPIPE:
# Test connectivity to npm registry
ping registry.npmjs.org
# Check current proxy settings
npm config get proxy
npm config get https-proxy
# Set proxy if behind a corporate firewall
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
# Or in Dockerfile
RUN npm config set proxy $HTTP_PROXY && \
npm config set https-proxy $HTTPS_PROXY && \
npm installIf you're not using a proxy, ensure these are unset:
npm config delete proxy
npm config delete https-proxySome CI environments need the HOME variable set explicitly:
# In your CI config or Dockerfile
export HOME=/root
npm installOr in a Dockerfile:
ENV HOME=/root
RUN npm ciIn GitLab CI:
variables:
HOME: "."
install_dependencies:
script:
- npm ciIf connections are timing out, increase npm's timeout values:
# Increase network timeout (in milliseconds)
npm config set fetch-timeout 60000
npm config set fetch-retries 5
# Or use environment variables
export npm_config_fetch_timeout=60000
npm installFor CI environments, add these to your build configuration:
# GitHub Actions example
- run: |
npm config set fetch-timeout 60000
npm ciCorrupted workspace state can cause EPIPE. Clean it before installing:
# Remove node_modules and lock file
rm -rf node_modules
rm -f package-lock.json
# Fresh install
npm installIn Jenkins, use the workspace cleanup plugin or:
cleanWs()In GitLab CI, ensure fresh clones:
variables:
GIT_STRATEGY: clone### Understanding EPIPE at the System Level
EPIPE is a POSIX signal (SIGPIPE) that occurs when a process attempts to write to a pipe whose read end has been closed. In the context of npm:
1. npm opens an HTTP connection to the registry
2. The registry streams package data
3. If the connection drops mid-transfer, the write end tries to continue
4. The OS signals EPIPE because nothing is reading anymore
### Node.js v16.18.0 Breaking Change
In October 2022, Node.js v16.18.0 changed how it handles certain I/O operations, which broke npm ci in CI/CD environments. The fix was released in later versions, but many CI pipelines using node:latest or node:16 Docker images were affected.
### Memory-Related EPIPE Errors
In constrained environments (CI runners, small Docker containers), npm can trigger EPIPE when:
- Memory limits cause the process to be killed mid-operation
- Swap space is exhausted
- Container OOM killer terminates child processes
To diagnose:
# Check memory during npm install
npm install &
watch -n 1 'free -m'### AWS CodeBuild Specific Fix
If you encounter EPIPE in AWS CodeBuild, invalidate the project cache:
aws codebuild invalidate-project-cache --project-name your-projectOr configure the buildspec to not cache npm:
cache:
paths: [] # Disable caching### Programmatic Error Handling
If you're spawning npm from Node.js code, handle EPIPE errors:
const { spawn } = require('child_process');
const npm = spawn('npm', ['install']);
npm.stdout.on('error', (err) => {
if (err.code === 'EPIPE') {
console.log('Pipe closed, retrying...');
// Implement retry logic
}
});
process.stdout.on('error', (err) => {
if (err.code === 'EPIPE') {
process.exit(0); // Graceful exit on pipe close
}
});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 ETOOMANYARGS npm ERR! Too many arguments
How to fix "npm ERR! code ETOOMANYARGS - Too many arguments"
npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names cannot contain spaces
How to fix "npm ERR! code EINVALIDTAGNAME - tag names cannot contain spaces"
npm ERR! code E400 npm ERR! 400 Bad Request
How to fix "npm ERR! code E400 - 400 Bad Request" error