Node.js "Maximum call stack size exceeded" - When to Use --stack-size

A RangeError: Maximum call stack size exceeded means the call stack overflowed - almost always unbounded or too-deep recursion. Raising --stack-size only buys a slightly deeper stack and usually just delays the crash.

What this error means

A run aborts with RangeError: Maximum call stack size exceeded, often with a long repeating frame in the stack. It is deterministic for a given input - the same data overflows the same way every time.

Node output

RangeError: Maximum call stack size exceeded
    at walk (/app/src/tree.js:12:16)
    at walk (/app/src/tree.js:18:5)
    at walk (/app/src/tree.js:18:5)
    ... (repeats)

Common causes

Unbounded or accidental infinite recursion

A recursive function with a missing or wrong base case, or two functions calling each other, never stops. The repeating frame in the stack names the culprit.

Legitimately very deep recursion

Occasionally the recursion is correct but the data is genuinely deep (a huge tree). Here the algorithm should be made iterative rather than relying on a bigger stack.

How to fix it

Fix the recursion (preferred)

Add or correct the base case, or rewrite deep recursion as iteration with an explicit stack. This is the real fix - the error never passes on retry.

tree.js

// iterative traversal instead of deep recursion
function walk(root) {
  const stack = [root];
  while (stack.length) {
    const node = stack.pop();
    visit(node);
    stack.push(...node.children);
  }
}

Raise --stack-size only as a stopgap

For genuinely deep-but-finite recursion you can enlarge the stack, but an oversized stack can itself crash the process, so prefer the iterative rewrite.

Terminal

node --stack-size=4000 app.mjs

How to prevent it

Ensure every recursive function has a correct base case.
Convert deep traversals to iteration for unbounded inputs.
Treat the RangeError as a logic bug, not something to retry.