Why Node.js Child Processes Hang: Understanding stdio, Pipes, and Data Consumption

child_process.spawn(command[, args][, options])

When using

child_process.spawn()

, the

options.stdio

property determines how the child process's standard streams are connected. It can be a string or an array.

command

: the command to execute.

args

: optional command‑line arguments.

options

: additional options, most importantly

stdio

.

The

options.stdio

value may be a string such as

'pipe'

,

'inherit'

,

'ignore'

, or an array like

['pipe','pipe','pipe']

. When it is an array, each element corresponds to a file descriptor (fd) for

stdin

,

stdout

, and

stderr

of the child process.

If

options.stdio

is omitted, Node.js creates three

Stream

objects:

child.stdin

,

child.stdout

, and

child.stderr

. The default configuration is equivalent to

['pipe','pipe','pipe']

, meaning each stream is a pipe that connects the parent and child processes.

Each element of the

stdio

array can be one of the following:

'pipe'

: creates a pipe between the parent and child; the child’s fd is exposed as

child.stdio[0‑2]

and maps to

child.stdin

,

child.stdout

,

child.stderr

.

'ipc'

: creates an IPC channel (used only for Node.js processes, not for

stdio

).

'ignore'

: redirects the fd to

/dev/null

.

'inherit'

: inherits the corresponding fd from the parent process.

Stream

: a readable or writable stream object (TTY, file, socket, pipe, etc.) that has an underlying fd.

Positive integer: a raw file descriptor.

null

or

undefined

: leaves the fd at its default value (

'pipe'

for the first three,

'ignore'

for the rest).

If a child process writes to a pipe whose output is not being consumed, the pipe’s buffer (typically 64 KB on Linux) will eventually fill, causing the child to block. This is why attaching a

on('data')

listener—or otherwise consuming the stream—is essential when

stdio

is set to

'pipe'

or

'inherit'

.

Experiment

We create a simple child script (

child.js

) that writes to

stdout

. In the parent script (

index.js

) we first run the child with the default configuration and observe the expected output.

Adding a

child.stdout.on('data', ...)

handler consumes the data and the process exits cleanly. Removing the handler while the child writes a large amount of data causes the pipe buffer to fill and the child process hangs.

Debugging with

gdb

on a compiled C child program (

child.c

) shows the hang occurring at the

printf

call, confirming that the write blocks when the pipe buffer is full.

Unix Domain Socket Buffer

When

options.stdio

is set to

'pipe'

, Node.js actually creates a Unix Domain Socket with a default buffer size of 65 536 bytes. If the child writes more than this without the parent reading, the buffer fills and the child blocks.

Why the Parent Must Read

Node.js streams start in a paused state. Adding a

'data'

listener (or calling

stream.resume()

or

stream.pipe()

) switches the stream to flowing mode, allowing data to be read. Without a listener, the internal buffer grows until it reaches the high‑water mark (default 16 KB). Once the buffer is full, the child’s write call blocks.

All Readable streams begin in paused mode but can be switched to flowing mode in one of the following ways: Adding a 'data' event handler. Calling the stream.resume() method. Calling the stream.pipe() method to send the data to a Writable.

The Node.js documentation states:

By default, pipes for stdin, stdout, and stderr are established between the parent Node.js process and the spawned child. These pipes have limited (and platform‑specific) capacity. If the child process writes to stdout in excess of that limit without the output being captured, the child process will block waiting for the pipe buffer to accept more data. This is identical to the behavior of pipes in the shell. Use the { stdio: 'ignore' } option if the output will not be consumed.

Therefore, when spawning a child with

stdio: 'pipe'

, you must either consume the data (e.g., attach

on('data')

) or explicitly ignore the streams using

{ stdio: 'ignore' }

to prevent the child from hanging.