EC
ERR_CHILD_PROCESS_UNSUPPORTED_OPTION
Node.jsERRORNotableChild ProcessHIGH confidence

Unsupported option passed to child_process function

Production Risk

Low — caught at startup; choose the right child_process function for your use case.

What this means

Thrown when an option that is not supported by the specific child_process function is passed to it. Different functions (spawn, fork, exec, execFile) support different option sets; some options are mutually exclusive or only valid for specific functions.

Why it happens
  1. 1Passing a shell option to fork() which does not support it
  2. 2Combining mutually exclusive options in a child_process call
  3. 3Typo in an option name causing it to be unrecognised
How to reproduce

Triggered when the child_process module validates options and finds an incompatible or unknown option.

trigger — this will error
trigger — this will error
const { fork } = require('child_process');
fork('./worker.js', { shell: true }); // shell not supported by fork()

expected output

Error [ERR_CHILD_PROCESS_UNSUPPORTED_OPTION]: options.shell is not supported for fork()

Fix 1

Use the correct function for your options

WHEN When you need shell features

Use the correct function for your options
const { exec } = require('child_process');
// exec() supports shell execution
exec('ls -la', (err, stdout) => { console.log(stdout); });

Why this works

exec() and spawn() with shell:true support shell features; fork() is for Node.js module IPC.

Fix 2

Check the Node.js docs for supported options per function

WHEN Before using a new option

Check the Node.js docs for supported options per function
// fork() supported options: cwd, env, execPath, execArgv, silent, stdio, uid, gid, serialization, signal, killSignal, timeout
const child = fork('./worker.js', { silent: true, uid: 1000 });

Why this works

Using only documented options for each function avoids validation errors.

Code examples
Triggerjs
const { fork } = require('child_process');
fork('./worker.js', { shell: true }); // shell not supported by fork()  // this triggers ERR_CHILD_PROCESS_UNSUPPORTED_OPTION
Handle in try/catchjs
try {
  // operation that may throw ERR_CHILD_PROCESS_UNSUPPORTED_OPTION
  riskyOperation()
} catch (err) {
  if (err.code === 'ERR_CHILD_PROCESS_UNSUPPORTED_OPTION') {
    console.error('ERR_CHILD_PROCESS_UNSUPPORTED_OPTION:', err.message)
  } else {
    throw err
  }
}
Defensive pattern to avoid itjs
// Validate inputs before calling the operation
function safe_err_child_process_unsupported_option(...args) {
  // validate args here
  return performOperation(...args)
}
What not to do

✕ Pass shell or argv0 to fork()

fork() has a restricted option set; unsupported options throw immediately.

Same error in other languages
TypeErrorin Python→
Sources
Official documentation ↗

Node.js Error Codes Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Node.js errors