How to fix TypeError: process.kill() invalid signal (signal name not recognized) in Node.js

Node.jsINTERMEDIATEMEDIUMUpdated Dec 9, 2025· 190 views

This error occurs when you pass an invalid or unrecognized signal name to Node.js process.kill(). Common causes include using signal numbers instead of names, omitting the SIG prefix, or using platform-specific signals on unsupported systems.

Quick fix

Fixes ERR_UNKNOWN_SIGNAL

// ✅ CORRECT
process.kill(pid, 'SIGTERM');
process.kill(pid, 'SIGINT');
process.kill(pid, 'SIGKILL');

// ❌ WRONG - numeric values
process.kill(pid, 15);  // TypeError

// ❌ WRONG - missing SIG prefix
process.kill(pid, 'TERM');  // TypeError

// ❌ WRONG - lowercase
process.kill(pid, 'sigterm');  // TypeError
  1. Use the full uppercase signal name with SIG prefix
  2. Check for platform-specific signal compatibility
  3. Validate signal names before use
  4. Handle cross-platform graceful shutdown
node.js — error
// ✅ CORRECT
process.kill(pid, 'SIGTERM');
process.kill(pid, 'SIGINT');
process.kill(pid, 'SIGKILL');
// ❌ WRONG - numeric values
process.kill(pid, 15);  // TypeError
// ❌ WRONG - missing SIG prefix
process.kill(pid, 'TERM');  // TypeError
// ❌ WRONG - lowercase
process.kill(pid, 'sigterm');  // TypeError
TypeError: process.kill() invalid signal (signal name not recognized)

What this error means

This TypeError indicates that Node.js could not recognize the signal you passed to `process.kill()`. Unlike Unix system calls that accept numeric signal values, Node.js requires specific string signal names. The error typically appears as `TypeError [ERR_UNKNOWN_SIGNAL]: Unknown signal: <your-value>`, where the value you provided doesn't match any of the standard POSIX signal names that Node.js recognizes. Node.js validates signal names to ensure cross-platform compatibility and prevent errors from platform-specific signals being used where they're not supported.

Typical symptoms

  • TypeError thrown when calling process.kill() with a signal argument
  • Error message mentions 'Unknown signal' or 'invalid signal'
  • Process termination code fails in production but might work locally
  • Windows-specific signal handling failures in cross-platform applications
  • Child process management throws unexpected errors

Common causes

  1. Using numeric signal values (like 15 for SIGTERM) instead of string names
  2. Omitting the 'SIG' prefix from signal names (using 'TERM' instead of 'SIGTERM')
  3. Using platform-specific signals like SIGUSR1 or SIGUSR2 on Windows
  4. Typos in signal names or using non-standard signal identifiers
  5. Attempting to use signals that don't exist in Node.js's signal map
  6. Using lowercase signal names instead of uppercase (like 'sigint' vs 'SIGINT')

How to fix "TypeError: process.kill() invalid signal (signal name not recognized)"

1Use the full uppercase signal name with SIG prefix

Always use the complete signal name in uppercase with the 'SIG' prefix:

javascript
// ✅ CORRECT
process.kill(pid, 'SIGTERM');
process.kill(pid, 'SIGINT');
process.kill(pid, 'SIGKILL');

// ❌ WRONG - numeric values
process.kill(pid, 15);  // TypeError

// ❌ WRONG - missing SIG prefix
process.kill(pid, 'TERM');  // TypeError

// ❌ WRONG - lowercase
process.kill(pid, 'sigterm');  // TypeError

If no signal is specified, Node.js defaults to 'SIGTERM'.

2Check for platform-specific signal compatibility

Verify that the signal you're using is supported on your target platform. Windows has limited signal support:

javascript
// Platform-safe signal handling
const signal = process.platform === 'win32' ? 'SIGTERM' : 'SIGUSR2';

try {
  process.kill(pid, signal);
} catch (err) {
  if (err.code === 'ERR_UNKNOWN_SIGNAL') {
    console.error(`Signal ${signal} not supported on this platform`);
    // Fallback to SIGTERM
    process.kill(pid, 'SIGTERM');
  }
}

Universally supported signals:
- SIGTERM - Graceful termination (Windows: can listen, cannot send)
- SIGINT - Interrupt (Ctrl+C)
- SIGKILL - Force kill
- SIGQUIT - Quit with core dump

Unix/Linux only:
- SIGUSR1, SIGUSR2 - User-defined signals
- SIGHUP - Hangup signal

3Validate signal names before use

If you're accepting signal names from configuration or user input, validate them against Node.js's recognized signals:

javascript
const VALID_SIGNALS = [
  'SIGABRT', 'SIGALRM', 'SIGBUS', 'SIGCHLD', 'SIGCONT', 'SIGFPE',
  'SIGHUP', 'SIGILL', 'SIGINT', 'SIGIO', 'SIGIOT', 'SIGKILL',
  'SIGPIPE', 'SIGPOLL', 'SIGPROF', 'SIGPWR', 'SIGQUIT', 'SIGSEGV',
  'SIGSTKFLT', 'SIGSTOP', 'SIGSYS', 'SIGTERM', 'SIGTRAP', 'SIGTSTP',
  'SIGTTIN', 'SIGTTOU', 'SIGUNUSED', 'SIGURG', 'SIGUSR1', 'SIGUSR2',
  'SIGVTALRM', 'SIGWINCH', 'SIGXCPU', 'SIGXFSZ', 'SIGBREAK'
];

function killProcess(pid, signal = 'SIGTERM') {
  if (!VALID_SIGNALS.includes(signal)) {
    throw new Error(`Invalid signal: ${signal}`);
  }

  return process.kill(pid, signal);
}

Alternatively, use os.constants.signals to check available signals:

javascript
import os from 'os';

function isValidSignal(signal) {
  return signal in os.constants.signals;
}

if (isValidSignal('SIGTERM')) {
  process.kill(pid, 'SIGTERM');
}
4Handle cross-platform graceful shutdown

For robust cross-platform process termination, implement a fallback strategy:

javascript
function terminateProcess(pid, graceful = true) {
  const isWindows = process.platform === 'win32';

  if (graceful) {
    try {
      // Try graceful shutdown first
      if (isWindows) {
        // Windows doesn't fully support SIGTERM
        process.kill(pid, 'SIGINT');
      } else {
        process.kill(pid, 'SIGTERM');
      }

      // Give process time to clean up
      return new Promise((resolve) => {
        const timeout = setTimeout(() => {
          // Force kill if not terminated
          process.kill(pid, 'SIGKILL');
          resolve();
        }, 5000);

        // Clear timeout if process exits
        const interval = setInterval(() => {
          try {
            process.kill(pid, 0); // Check if process exists
          } catch {
            clearTimeout(timeout);
            clearInterval(interval);
            resolve();
          }
        }, 100);
      });
    } catch (err) {
      if (err.code !== 'ESRCH') { // Process doesn't exist
        throw err;
      }
    }
  } else {
    // Force kill
    process.kill(pid, 'SIGKILL');
  }
}

Advanced notes

Signal Zero for Process Existence Checking

You can pass signal 0 to process.kill() to check if a process exists without actually sending a signal. This is useful for process monitoring:

javascript
function isProcessRunning(pid) {
  try {
    process.kill(pid, 0);
    return true;
  } catch (err) {
    return err.code === 'EPERM'; // Process exists but no permission
  }
}

Unsafe Signals

Some signals should never have listeners in Node.js because they leave the process in an unsafe state: SIGBUS, SIGFPE, SIGSEGV, and SIGILL. Attempting to handle these artificially can cause undefined behavior.

Signal Name Evolution

Prior to Node.js v12, signal numbers were sometimes accepted, but this was removed for consistency and cross-platform compatibility. Always use string signal names in modern Node.js applications.

Process Groups on Unix

On Unix systems, you can send signals to process groups using negative PIDs with process.kill(), but this doesn't work on Windows. Use platform-specific libraries like tree-kill for cross-platform process tree termination.

Frequently asked questions

What does "ERR_UNKNOWN_SIGNAL" mean?
kill(). js requires specific string signal names. js recognizes.
How do I fix "ERR_UNKNOWN_SIGNAL"?
This error occurs when you pass an invalid or unrecognized signal name to Node.js process.kill(). Common causes include using signal numbers instead of names, omitting the SIG prefix, or using platform-specific signals on unsupported systems.
What causes "ERR_UNKNOWN_SIGNAL"?
Using numeric signal values (like 15 for SIGTERM) instead of string names Omitting the 'SIG' prefix from signal names (using 'TERM' instead of 'SIGTERM') Using platform-specific signals like SIGUSR1 or SIGUSR2 on Windows
Is the "ERR_UNKNOWN_SIGNAL" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading