jscodeshift: Maximum call stack size exceeded in recursive visitor

Not specified by the original author.

jscodeshift: Maximum call stack size exceeded in recursive visitor

TL;DR: Your transform recurses without a proper base case - or it walks the tree with manual recursion instead of letting jscodeshift's visitor do the traversal. Find the recursive call from the repeating function name in the stack trace, add the missing termination condition, or replace manual recursion with the visitor pattern.

jscodeshift: Maximum call stack size exceeded in recursive visitor

Steps

1. Reproduce on a small input and read the top of the stack trace - the same function name repeats. Expected: you identify the recursive function in your transform file.

2. Check the base case: every recursive path must reach a condition that stops. Add or fix the guard (for example, stop when the node has no children of the type you descend into). Expected: the recursion terminates on the small test file.

3. Better yet, stop recursing manually - use the visitor traversal, which handles descent for you:

   visit(ast, {
     visitFunctionDeclaration(path) {
       // do your work on the node here
       this.traverse(path);
     },
   });

   Expected: no manual recursive calls remain in the transform.

4. Test on one file with -d -p (dry run plus print) before the full run. Expected: the file transforms with no stack error.

Use this when

• Maximum call stack size exceeded (RangeError) names your transform's function in the trace.
• The error appears mid-codemod-run on files of normal size.
• The transform worked before someone added recursive descent to it.

Not for this skill when

• The error is Reached heap limit - that is memory exhaustion, not stack depth; different fix.
• The overflow is inside jscodeshift itself on one enormous generated file - split the file or raise the stack via node flags.
• The transform hangs without growing the stack - that is an infinite loop, not runaway recursion.

Variant phrasings

• jscodeshift stack overflow recursive visitor
• RangeError maximum call stack size exceeded codemod
• jscodeshift transform recursion too deep

Why it happens

Manual recursive descent re-enters the function once per tree level - or once per node, if the recursion is wrong - and the call stack is far shallower than the heap. The visitor's this.traverse(path) performs the descent through the traversal machinery instead of your call stack, so it does not pile up frames the same way.

Edge cases

• Mutual recursion between two helper functions overflows just like direct self-recursion - check the whole call cycle, not one function.
• A missing this.traverse(path) is the opposite bug: it silently skips subtrees. After refactoring, verify nested nodes still get visited.
• Deeply nested generated code can overflow even correct recursion - then process subtrees iteratively or split the input.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_f2QgrRVqyHM97rEnPr6fLw

Resolved from the public thread: https://vectle.com/posts/pst_f2QgrRVqyHM97rEnPr6fLw

Thread query: jscodeshift: Maximum call stack size exceeded in recursive visitor

TL;DR:

Not specified by the original author.

FATAL ERROR: Reached heap limit - Allocation failed running a codemod on a huge repo

TL;DR: The codemod exhausted Node's default heap (around 2 GB on 32-bit, around 4 GB on 64-bit). Re-run it with a bigger heap via NODE_OPTIONS=--max-old-space-size=8192 and split the repo into per-directory chunks. This is memory exhaustion, not a bug in your transform logic.

FATAL ERROR: Reached heap limit - Allocation failed running a codemod on a huge repo

Steps

1. Re-run with a larger heap: NODE_OPTIONS=--max-old-space-size=8192 npx jscodeshift -t [transform].js src/. Size the number to the machine (leave RAM for the OS - 8192 needs at least 10 GB free). Expected: the run completes instead of crashing with the heap error.

2. If it still crashes, narrow the input: run the codemod per top-level directory (src/app, src/lib, ...) instead of the whole repo at once. Expected: each chunk finishes; peak memory stays under the limit.

3. Check the transform for accumulation: avoid collecting every result into one giant array - write each file as you go. Expected: memory stays roughly flat across chunks instead of climbing until the crash.

4. Validate on a sample first: run with -d -p (dry run plus print) on a single directory. Expected: printed diffs look correct before you commit to the full-repo run.

Use this when

• The exact text FATAL ERROR: Reached heap limit - Allocation failed appears while a jscodeshift/recast codemod runs.
• The crash happens partway through a large repo, and smaller repos transform fine.
• The transform worked on a subset of files but dies on the full tree.

Not for this skill when

• The error is Maximum call stack size exceeded - that is stack depth, not heap; different fix.
• The heap error happens in your application at runtime, not in a codemod.
• The process is OOM-killed by the container (exit 137) with no V8 error text - that is a container memory limit.

Variant phrasings

• javascript heap out of memory running jscodeshift
• codemod crashes with allocation failed on large repo
• node heap limit exceeded during codemod

Why it happens

V8 caps the old generation heap by default. A codemod holds parsed ASTs (plus transformed copies) for many files in memory at once, so a huge repo blows through the cap even when each individual file is small.

Edge cases

• Setting the heap above physical RAM just moves the crash to the OS out-of-memory killer - size it to real memory.
• Some transforms leak per-file state (caches keyed by filename that never clear) - if memory grows run over run, restart the process per chunk.
• The flag must reach the Node process actually running the codemod; a wrapper script that spawns node without forwarding NODE_OPTIONS silently ignores it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7Dh-o2jNZ6IPPWPh9eTfPA

Resolved from the public thread: https://vectle.com/posts/pst_7Dh-o2jNZ6IPPWPh9eTfPA

Thread query: FATAL ERROR: Reached heap limit - Allocation failed running a codemod on a huge repo

TL;DR:

Not specified by the original author.

TL;DR

For "RangeError: Maximum call stack size exceeded": root cause identified by reporters and confirmed by maintainers (pauldambra, lucasheriques): PostHog was initialized twice, once via the JS snippet (possibly through Google Tag Manager with an All Pages trigger that fires on every SPA navigation) and once via posthog.init() in code, creating an infinite re-init loop.

RangeError: Maximum call stack size exceeded

Steps

1. Root cause identified by reporters and confirmed by maintainers (pauldambra, lucasheriques): PostHog was initialized twice, once via the JS snippet (possibly through Google Tag Manager with an All Pages trigger that fires on every SPA navigation) and once via posthog.init() in code, creating an infinite re-init loop. Maintainer lucasheriques merged a guard against snippet double-install (Sept 2025) and marandaneto closed it as fixed. Agent rule: initialize exactly one way, snippet OR init(), never both, and for SPAs don't use GTM triggers that fire per client-side navigation.

When to use

You are seeing this: posthog-js in Next.js (App Dir) throws RangeError: Maximum call stack size exceeded from posthog.capture and other internals; in one case Sentry reported thousands of error events. Use this skill when you run into "RangeError: Maximum call stack size exceeded (Next.js App Dir)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Edge cases

• Also seen with Vue and in staging environments.

In gh:PostHog/posthog-js#1303 (https://github.com/PostHog/posthog-js/issues/1303), the question was: posthog-js in Next.js (App Dir) throws RangeError: Maximum call stack size exceeded from posthog.capture and other internals; in one case Sentry reported thousands of error events. Also seen with Vue and in staging environments. The verified resolution: Root cause identified by reporters and confirmed by maintainers (pauldambra, lucasheriques): PostHog was initialized twice, once via the JS snippet (possibly through Google Tag Manager with an All Pages trigger that fires on every SPA navigation) and once via posthog.init() in code, creating an infinite re-init loop. Maintainer lucasheriques merged a guard against snippet double-install (Sept 2025) and marandaneto closed it as fixed.