Notes

Find why Node and V8 deoptimize a function

Use V8 optimization traces to identify the invalidated assumption, then reproduce it with a controlled input change before changing application code.

Run a representative workload with --trace-opt --trace-deopt and find the function name and bailout reason. A deoptimization means optimized code’s assumptions stopped holding, so V8 transfers execution to a more general tier. It preserves JavaScript behavior. One bailout during warmup is not proof of a performance problem; correlate repeated bailouts with CPU profiles and request latency.

Start with ordinary tracing

node --trace-opt --trace-deopt app.cjs
node --v8-options | rg "trace-opt|trace-deopt|allow-natives-syntax"
node -p "process.versions.v8"

app.cjs is your workload’s entry point. Redirect both stdout and stderr if you need a complete capture. Node’s CLI documentation describes passing V8 options and inspecting the locally available flags. V8 flags and trace formats can change between Node versions.

Force the transition in a small experiment

This diagnostic script deliberately changes an object’s shape and then overflows an integer-specialized addition. Save it as deopt.cjs:

function field(o) { return o.x + 1; }
%PrepareFunctionForOptimization(field);
for (let i = 0; i < 10000; i++) field({x: i});
%OptimizeFunctionOnNextCall(field);
console.log(field({x: 1}));
console.log(field({x: 1, y: 2}));
function add(a, b) { return a + b; }
%PrepareFunctionForOptimization(add);
for (let i = 0; i < 10000; i++) add(i, 1);
%OptimizeFunctionOnNextCall(add);
console.log(add(1, 2));
console.log(add(2147483647, 1));
console.log(add("a", 1));
node --trace-opt --trace-deopt --allow-natives-syntax deopt.cjs

The percent-prefixed intrinsics are V8 internals, not standard JavaScript. PrepareFunctionForOptimization prepares feedback collection; OptimizeFunctionOnNextCall requests optimization for the next call. Use these only in controlled experiments, not shipped application code. Their accepted forms are tied to the V8 version.

Example output from Node 26.13.0, trimmed to the relevant lines:

[manually marking 0x3a3dc7e6eee1 <JSFunction field (sfi = 0x2bac72f31669)> for optimization to TURBOFAN_JS, ConcurrencyMode::kSynchronous]
2
[bailout (kind: deopt-eager, reason: wrong map): begin. deoptimizing 0x3a3dc7e6eee1 <JSFunction field (sfi = 0x2bac72f31669)>, 0x078a19a70fd1 <Code TURBOFAN_JS>, opt id 0, bytecode offset 0, deopt exit 1, FP to SP delta 32, caller SP 0x7ffdc31e9b48, pc 0x7e73b4004de2]
2
[manually marking 0x3a3dc7e6ef21 <JSFunction add (sfi = 0x2bac72f316b1)> for optimization to TURBOFAN_JS, ConcurrencyMode::kSynchronous]
3
[bailout (kind: deopt-eager, reason: overflow): begin. deoptimizing 0x3a3dc7e6ef21 <JSFunction add (sfi = 0x2bac72f316b1)>, 0x0ca12fb44d61 <Code TURBOFAN_JS>, opt id 4, bytecode offset 2, deopt exit 2, FP to SP delta 32, caller SP 0x7ffdc31e9b48, pc 0x7e73b4004eec]
2147483648
a1

field optimized to TURBOFAN_JS, then encountered wrong map. The second object has another property and therefore a different hidden class, despite x still being present. The V8 hidden-class documentation explains these map transitions. The function still returns 2.

add optimized using small integer feedback, then the result exceeded its assumed integer range and triggered overflow. The result is still the correct Number, 2147483648. The subsequent string argument returns a1; it does not produce another bailout in this run because the earlier bailout has already discarded the specialized code.

Read reasons as evidence

Reason or trigger What to inspect
wrong map Different object layouts or array element representations at the same access site
overflow Numeric inputs/results beyond the representation assumed by optimized code
not a Smi A non-small-integer value reaches an integer-specialized path
Changed arguments Strings, missing arguments yielding undefined, or different object shapes change feedback

The V8 reason definitions name these bailouts; the flag definitions describe the tracing switches. A polymorphic call site may become generalized without repeatedly deoptimizing. Do not assume every argument variation guarantees a bailout, or that using the arguments object universally prevents optimization.

Fix a measured hot path by stabilizing construction order, initializing optional fields consistently where appropriate, or normalizing inputs at a boundary. Preserve valid numeric behavior; bitwise truncation to silence an overflow can change the answer. Benchmark realistic warmed-up traffic after the change.

Go deeper

The V8 deoptimization dive follows the transfer from specialized machine code back to a state that can handle the new input.