How to fix npm ERR! code SIGHUP npm ERR! errno SIGHUP npm ERR! Received SIGHUP in npm

npmINTERMEDIATEMEDIUMUpdated Dec 5, 2025· 132 views

The npm SIGHUP error occurs when the controlling terminal is closed or disconnected, typically during SSH sessions, remote deployments, or when terminal windows are closed while npm is running.

Quick fix

Fixes npm ERR! code SIGHUP npm ERR! errno SIGHUP npm ERR! Received SIGHUP

# For npm install
nohup npm install > install.log 2>&1 &

# For npm scripts
nohup npm run build > build.log 2>&1 &

# Check progress
tail -f install.log
  1. Use nohup for remote/persistent operations
  2. Use terminal multiplexers for SSH sessions
  3. Configure SSH keep-alive to prevent timeout
  4. Run Node directly instead of through npm
npm — error
# For npm install
nohup npm install > install.log 2>&1 &
# For npm scripts
nohup npm run build > build.log 2>&1 &
# Check progress
tail -f install.log
npm ERR! code SIGHUP
npm ERR! errno SIGHUP
npm ERR! Received SIGHUP

What this error means

SIGHUP (signal hangup) is a Unix/Linux signal sent to a process when its controlling terminal is closed or disconnected. Historically used to notify programs of modem hangups, it's now primarily triggered by terminal window closures, SSH session disconnections, or connection timeouts. When npm receives SIGHUP, it means the terminal that spawned the npm process has either closed, dropped the connection, or the controlling process terminated unexpectedly. This is particularly problematic during long-running operations like npm install in CI/CD pipelines, remote SSH sessions, or unstable network conditions. npm doesn't always handle this signal gracefully—it simply terminates with an error code rather than cleaning up resources properly.

Typical symptoms

  • npm install or npm run commands abort abruptly mid-execution without completion
  • Process exits with error code 129 (128 + signal 1) or similar signal-related codes
  • SSH sessions freeze or disconnect in the middle of npm operations
  • Build pipelines fail during dependency installation with no obvious cause
  • Terminal window closes unexpectedly while npm is still running

Common causes

  1. SSH session timeout or network disconnection during long npm operations
  2. Terminal window or tab closed while npm was still executing
  3. Unpredictable shell/terminal behavior on some systems with large dependency trees
  4. npm not properly handling or propagating signals to child processes
  5. Inadequate SSH keep-alive settings in sshd_config causing idle timeouts
  6. Process output tied to a closed pseudo-terminal causing SIGPIPE signal chain

How to fix "npm ERR! code SIGHUP npm ERR! errno SIGHUP npm ERR! Received SIGHUP"

1Use nohup for remote/persistent operations

The nohup (no hangup) utility allows processes to continue running even after terminal disconnection:

bash
# For npm install
nohup npm install > install.log 2>&1 &

# For npm scripts
nohup npm run build > build.log 2>&1 &

# Check progress
tail -f install.log

The > install.log 2>&1 redirects both stdout and stderr to a file, and & backgrounds the process.

2Use terminal multiplexers for SSH sessions

For remote SSH work, use a terminal multiplexer that survives SSH disconnection:

bash
# With tmux (recommended, more modern)
tmux new-session -d -s install "npm install"
tmux attach-session -t install

# Or with screen (older but widely available)
screen -d -m npm install
screen -ls                    # See running sessions
screen -r [session-id]        # Reconnect

Both tools create persistent pseudo-terminals that survive connection drops.

3Configure SSH keep-alive to prevent timeout

If SIGHUP is caused by SSH timeouts, adjust server-side keep-alive:

bash
# On the remote server, edit /etc/ssh/sshd_config
sudo nano /etc/ssh/sshd_config

# Add or modify these lines:
ClientAliveInterval 300
ClientAliveCountMax 3

# Restart SSH daemon
sudo systemctl restart sshd

On the client side, add to ~/.ssh/config:

bash
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
4Run Node directly instead of through npm

npm's signal handling has issues in some versions. Running node directly avoids this:

bash
# Instead of:
npm start

# Use:
node ./dist/index.js

For Procfile deployments (Heroku, etc.):

procfile
# Bad (npm signal handling issues)
web: npm start

# Better
web: node server.js
5Increase npm timeouts and use retry logic

For flaky networks or slow connections, increase npm's fetch timeout:

bash
# Set timeout to 5 minutes (300 seconds)
npm config set fetch-timeout 300000
npm config set fetch-retry-mintimeout 10000
npm config set fetch-retry-maxtimeout 120000

Or use a .npmrc file in your project root:

ini
fetch-timeout=300000
fetch-retry-mintimeout=10000
fetch-retry-maxtimeout=120000
fetch-retries=5

Advanced notes

Signal Handling Deep Dive: SIGHUP is signal #1 on POSIX systems. When a shell receives SIGHUP, it intercepts the signal and resends SIGHUP to all child processes in its job table before exiting. npm doesn't register a SIGHUP handler, so it simply terminates.

Docker Considerations: In Docker, SIGHUP can be sent when the PID 1 process terminates. The proper Docker solution is to use an init system (like dumb-init) and run npm indirectly: dumb-init npm install or simply node app.js without npm as a wrapper.

CI/CD Environments: Most CI/CD platforms (GitHub Actions, GitLab CI, CircleCI) don't send SIGHUP during normal job execution. If you see SIGHUP in CI, check for job timeout settings, dependency download timeouts, or OOM conditions.

stdout Buffering: A subtle issue: if npm's stdout/stderr is buffered and the terminal closes before the buffer flushes, the process may receive SIGPIPE instead. Using output redirection to files avoids this entirely.

Frequently asked questions

What does "npm ERR! code SIGHUP npm ERR! errno SIGHUP npm ERR! Received SIGHUP" mean?
SIGHUP (signal hangup) is a Unix/Linux signal sent to a process when its controlling terminal is closed or disconnected. Historically used to notify programs of modem hangups, it's now primarily triggered by terminal window closures, SSH session disconnections, or connection timeouts. When npm receives SIGHUP, it means the terminal that spawned the npm process has either closed, dropped the connection, or the controlling process terminated unexpectedly.
How do I fix "npm ERR! code SIGHUP npm ERR! errno SIGHUP npm ERR! Received SIGHUP"?
The npm SIGHUP error occurs when the controlling terminal is closed or disconnected, typically during SSH sessions, remote deployments, or when terminal windows are closed while npm is running.
What causes "npm ERR! code SIGHUP npm ERR! errno SIGHUP npm ERR! Received SIGHUP"?
SSH session timeout or network disconnection during long npm operations Terminal window or tab closed while npm was still executing Unpredictable shell/terminal behavior on some systems with large dependency trees
Is the "npm ERR! code SIGHUP npm ERR! errno SIGHUP npm ERR! Received SIGHUP" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading