How to fix npm ERR! code ESPIPE npm ERR! ESPIPE: invalid seek in npm

npmINTERMEDIATEHIGHUpdated Dec 5, 2025· 128 views

ESPIPE is a system-level error that occurs when npm or Node.js tries to seek (reposition) on a pipe or non-seekable file descriptor. This typically happens with virtual filesystems, large operations, or version mismatches.

Quick fix

Fixes ESPIPE

node --version

# Update to latest LTS (recommended: v20 or v22)
nvm install --lts
nvm use --lts

# Or using Node directly
# macOS/Linux:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows: Download from https://nodejs.org/
  1. Update Node.js to a newer LTS version
  2. Clear npm cache and reinstall
  3. Move project to a local filesystem
  4. Check for piped commands and avoid early termination
npm — error
node --version
# Update to latest LTS (recommended: v20 or v22)
nvm install --lts
nvm use --lts
# Or using Node directly
# macOS/Linux:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Windows: Download from https://nodejs.org/
npm ERR! code ESPIPE
npm ERR! ESPIPE: invalid seek

What this error means

ESPIPE stands for 'Error: Seek on Pipe' and is a POSIX system error that occurs when code attempts a seek operation on a file descriptor that doesn't support seeking, such as pipes, named FIFOs, or virtual filesystems. Unlike regular files, pipes are streams of data that cannot be randomly accessed or repositioned. When npm encounters this error during install, build, or other operations, it means the underlying Node.js process tried to reposition within what it expected to be a regular file, but received a non-seekable stream instead. This is often triggered by filesystem mismatches or how npm's internal file handling interacts with your system's I/O layer. The error is particularly common when using virtual or mounted filesystems (like GVFS, network drives, or container volumes) that don't behave like standard local storage.

Typical symptoms

  • npm install fails with 'ESPIPE: invalid seek' error message
  • npm operations timeout or hang before throwing the error
  • Error occurs intermittently, sometimes succeeding on retry
  • Works on local filesystem but fails when files are on network mounts or virtual filesystems
  • CI/CD pipelines fail during npm operations but work locally

Common causes

  1. Virtual or mounted filesystems (GVFS, SMB shares, NFS) that don't support seek operations properly
  2. Node.js version incompatibility with your system's file descriptor handling (especially Node v8.x-v10.x)
  3. npm cache corruption or corrupted file streams during large package installations
  4. Piping npm output to commands that close early (like 'head' or 'grep') causing broken pipe conditions
  5. Container or WSL environment with misaligned I/O buffering between host and guest systems
  6. Global npm cache location on a filesystem that doesn't support random file access

How to fix "npm ERR! code ESPIPE npm ERR! ESPIPE: invalid seek"

1Update Node.js to a newer LTS version

The ESPIPE error was addressed in Node.js v10.x and later versions. Check your current version and upgrade if necessary.

bash
node --version

# Update to latest LTS (recommended: v20 or v22)
nvm install --lts
nvm use --lts

# Or using Node directly
# macOS/Linux:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows: Download from https://nodejs.org/

After upgrading, clear npm cache and retry.

2Clear npm cache and reinstall

Corrupted cache files can trigger ESPIPE errors. Force clear the cache and reinstall dependencies.

bash
# Clear npm cache completely
npm cache clean --force

# Verify cache is clean
npm cache verify

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

# Reinstall from scratch
npm install

This removes any corrupted file pointers that might cause seek errors.

3Move project to a local filesystem

If your project is on a network mount, virtual filesystem, or WSL shared folder, move it to the host's native storage.

bash
# Check current directory filesystem type
df -T .

# Look for: gvfs, nfs, cifs, drvfs (WSL), vboxsf (VirtualBox)
# If found, move project to native storage:

# macOS/Linux example:
cp -r /mnt/network-drive/project /home/user/projects/project
cd /home/user/projects/project
npm install

# WSL: Move from /mnt/c/Users/... to /home/user/...

Virtual filesystems often don't support all POSIX file operations that npm expects.

4Check for piped commands and avoid early termination

If running npm through pipes (especially to 'head', 'grep', or similar), the pipe may close prematurely, triggering ESPIPE.

bash
# Avoid this pattern:
npm install | head -20  # ❌ Likely to cause ESPIPE
npm list | grep package  # ❌ Likely to cause ESPIPE

# Do this instead:
npm install > output.log
head -20 output.log  # ✓ Safe

# Or use npm filters directly:
npm list --depth=0  # ✓ Use npm's built-in flags

When pipes close unexpectedly, npm's file handles get corrupted.

5Configure npm to use a local cache directory

Force npm to use a cache location on your local (non-virtual) filesystem.

bash
# Create cache directory on local drive
mkdir -p ~/.npm-local-cache

# Configure npm to use it
npm config set cache ~/.npm-local-cache --global

# Verify the setting
npm config get cache

# Clear and reinstall
npm cache clean --force
npm install

This ensures npm's cache operations don't hit filesystem limitations.

Advanced notes

For WSL2 users: ESPIPE often occurs when npm is installed on the Windows side and called from WSL, or when the project is in /mnt/c/... (Windows host). Solution: Reinstall Node.js inside WSL (sudo apt install nodejs npm) and keep projects in native WSL storage (/home/...).

For Docker users: Mount the project as a volume with proper permissions. Use docker run -v $(pwd):/app instead of VirtualBox folder sharing when possible. Set Docker's native storage driver to overlay2 instead of aufs or btrfs.

For systems with corrupted inode caches: On Linux, you can check filesystem health with fsck (on unmounted partitions only), but first try the simpler fixes. Network mount issues may require contacting your system administrator to verify NFS/SMB export options support seeking.

Frequently asked questions

What does "ESPIPE" mean?
ESPIPE stands for 'Error: Seek on Pipe' and is a POSIX system error that occurs when code attempts a seek operation on a file descriptor that doesn't support seeking, such as pipes, named FIFOs, or virtual filesystems. Unlike regular files, pipes are streams of data that cannot be randomly accessed or repositioned. js process tried to reposition within what it expected to be a regular file, but received a non-seekable stream instead.
How do I fix "ESPIPE"?
ESPIPE is a system-level error that occurs when npm or Node.js tries to seek (reposition) on a pipe or non-seekable file descriptor. This typically happens with virtual filesystems, large operations, or version mismatches.
What causes "ESPIPE"?
Virtual or mounted filesystems (GVFS, SMB shares, NFS) that don't support seek operations properly Node.js version incompatibility with your system's file descriptor handling (especially Node v8.x-v10.x) npm cache corruption or corrupted file streams during large package installations
Is the "ESPIPE" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading