Deoptimization: How V8 Throws Away Optimized Code

Jay Hubbert — Thu, 22 Oct 2026 15:10:00 +0000

TL;DR: When a TurboFan guard fails, the deoptimizer has to rebuild an interpreter frame from nothing but the machine registers and a stack frame full of optimized values. The recipe is a byte-coded stream of translation opcodes emitted at compile time and stored in a DeoptimizationData object next to the code. The deopt reason is not in that stream at all - it is in the relocation info, keyed by PC, so V8 only pays for it when someone is actually looking.

Speculative compilation is a bet. TurboFan looks at a function, decides that the object at obj.x is a JSObject with a particular Map, that f is always the same closure, that arr[i] never goes out of bounds, and it emits machine code that assumes all of that without re-checking.

Sometimes the bet is wrong. The object turns out to be a JSProxy. The array turns out to be one element shorter than the code thought. The map got deprecated and migrated. At that moment V8 has to undo the bet, and undoing it is the most delicate thing in the whole engine - it has to reconstruct a frame layout that the optimizer deliberately threw away.

A deopt is a correctness mechanism, not a failure

The framing matters, because “deopt” sounds like an error. It is not. A deopt is the only correct response to a violated assumption. The alternative - continuing to run code that has already demonstrated it is operating on a wrong map - is undefined behaviour, and in V8’s case it is a memory-safety bug, not a wrong answer.

The compiler’s job is to make the common case fast and the uncommon case correct. The deoptimizer is the bridge between the two worlds. It is also why V8 can speculate at all: because the escape hatch is cheap enough (relatively) that TurboFan is free to be aggressive.

Concretely, V8’s deopt machinery has three levels of granularity, and they are worth separating because they have completely different costs.

 cpp
 
 
// src/common/globals.h:1028
enum class DeoptimizeKind : uint8_t {
 kEager,
 kLazyAfterFastCall,
 kLazy,
};

An eager deopt means the frame is rewritten right now: the machine registers are spilled into a FrameDescription, the translation stream is walked, and interpreter frames are built on the stack. The bytecode offset the interpreter resumes at is the one the deopt happened at.

A lazy deopt means the current operation is allowed to finish first. The frame is only deoptimized once the operation completes, and the interpreter resumes at the next bytecode. The kLazyAfterFastCall variant is the same thing for a deopt that follows a direct call into C++ - the source has a TODO admitting the name is now a lie, because it is used for every direct call to C++ and not just for fast API calls.

The choice between eager and lazy is made at code-generation time, and it is not a heuristic - it is a property of the graph node that bailed out. A node that has already written to memory cannot be rolled back lazily; a node that has only read can.

Soft deopt: mark the code, patch the stack

The third mechanism is the one that does not rewrite anything immediately, and it is the one you hit most often in practice. When the world changes underneath a function that is already running, V8 cannot rewrite that function’s frame on the spot. Instead it marks the code object and patches the return addresses on the stack so that the frames deopt when they return.

 cpp
 
 
// src/objects/code.cc:166
void Code::SetMarkedForDeoptimization(Isolate* isolate,
 LazyDeoptimizeReason reason) {
 // We've already marked for deoptimization, return.
 if (marked_for_deoptimization()) return;
 set_marked_for_deoptimization(true);
 // Eager deopts are already logged by the deoptimizer.

The reason this is a “soft” deopt is that the machine code is still there. The function continues running, correctly, right up until the moment it returns. Then the patched return address sends it into the deopt entry instead.

The patch itself is a stack walk. Deoptimizer::DeoptimizeMarkedCode finds every activation of the marked code on every thread and rewrites the return address slot in the caller’s frame:

 cpp
 
 
// src/deoptimizer/deoptimizer.cc:366
 for (StackFrameIterator it(isolate, top); !it.done(); it.Advance()) {
 if (it.frame()->is_optimized_js()) {
 Tagged<GcSafeCode> code = it.frame()->GcSafeLookupCode();
 if (CodeKindCanDeoptimize(code->kind()) &&
 code->marked_for_deoptimization()) {
 // Obtain the trampoline to the deoptimizer call.
 int trampoline_pc;

The trampoline address comes from the code’s safepoint table - the same table that lets a GC find the live slots in an optimized frame. So V8 reuses one structure for two purposes: “where are the live references?” and “where do I jump if I have to bail out?”.

Once the code is marked, SetMarkedForDeoptimization also does something nasty and clever: it zaps the deopt exits.

 cpp
 
 
// src/objects/code.cc:227
 Tagged<ProtectedFixedArray> tmp = deoptimization_data();
 // TODO(422951610): Zapping code discovered a bug in
 // --maglev-inline-api-calls. Remove the flag check here once the bug is
 // fixed.
 if (tmp->ulength().value() > 0 && !v8_flags.maglev_inline_api_calls) {
 Address start = instruction_start();
 Address end = start + deoptimization_data()->DeoptExitStart().value();
 RelocIterator it(instruction_stream(), RelocIterator::kAllModesMask);
 Deoptimizer::ZapCode(start, end, it);
 }

Everything before the deopt exits - the hot code - is left alone. The deopt exits themselves are overwritten with trapping instructions. The point is that a marked code object must never be entered again, and rather than maintaining a flag check on every entry, V8 makes the deopt exits themselves explode. If a stale reference to that code is called, you get a trap instead of silently running code whose assumptions no longer hold.

The LazyDeoptimizeReason enum is the vocabulary of “why did the world change underneath us”:

 cpp
 
 
// src/deoptimizer/deoptimize-reason.h:109
#define LAZY_DEOPTIMIZE_REASON_LIST(V) \
 V(MapDeprecated, "dependent map was deprecated") \
 V(PrototypeChange, "dependent prototype chain changed") \
 V(PropertyCellChange, "dependent property cell changed") \
 V(FieldTypeConstChange, "dependent field type constness changed") \
 V(FieldTypeChange, "dependent field type changed") \
 V(FieldRepresentationChange, "dependent field representation changed") \
 V(InitialMapChange, "dependent initial map changed") \
 V(AllocationSiteTenuringChange, \
 "dependent allocation site tenuring changed") \
 V(AllocationSiteTransitionChange, \
 "dependent allocation site transition changed") \
 V(ContextCellChange, "dependent context cell state changed") \
 V(EmptyContextExtensionChange, "dependent empty context extension changed") \
 V(WeakObjects, "embedded weak objects cleared") \
 V(Debugger, "JS debugger attached") \
 V(Testing, "for testing") \
 V(ExceptionCaught, "exception with omitted catch handler") \
 V(EagerDeopt, "marked due to eager deopt") \
 V(FrameValueMaterialized, "value in stack frame was materialized")

Note MapDeprecated and PrototypeChange at the top. Those are not “something went wrong” - those are the normal consequences of a program mutating an object’s shape. The deopt is how V8 tells the optimizer “your assumption about this map is stale, recompile”.

The deopt data: what the runtime actually walks

Everything the deoptimizer needs is in a DeoptimizationData object hanging off the Code object. It is a fixed array with a fixed layout:

 cpp
 
 
// src/objects/deoptimization-data.h:264
 // Layout description. Indices in the array.
 static const int kFrameTranslationIndex = 0;
 static const int kInlinedFunctionCountIndex = 1;
 static const int kProtectedLiteralArrayIndex = 2;
 static const int kLiteralArrayIndex = 3;
 static const int kOsrBytecodeOffsetIndex = 4;
 static const int kOsrPcOffsetIndex = 5;
 static const int kOptimizationIdIndex = 6;
 static const int kWrappedSharedFunctionInfoIndex = 7;
 static const int kInliningPositionsIndex = 8;
 static const int kDeoptExitStartIndex = 9;
 static const int kEagerDeoptCountIndex = 10;
 static const int kLazyDeoptCountIndex = 11;
 static const int kFirstDeoptEntryIndex = 12;

Slot 0 is the frame translation: a DeoptimizationFrameTranslation, which is a TrustedByteArray holding a stream of opcodes. Slots 12 onwards are the per-deopt-point entries, each of which is (bytecode offset, translation index, pc offset) - and in debug builds, a node id.

The translation stream is the interesting part. It is a bytecode of its own:

Read it as a recipe. BEGIN_WITH_FEEDBACK starts a frame; then one opcode per value in the frame, telling the deoptimizer where the value lives (REGISTER 3 = “register 3 holds this local”), what it is (DOUBLE_REGISTER vs REGISTER vs BOOL_REGISTER), and where to put it in the rebuilt frame. OPTIMIZED_OUT means the optimizer deleted this value entirely - it is not live, so the interpreter frame gets undefined there. CAPTURED_OBJECT is the escape-analysis case: an object the optimizer proved does not escape, so it was never allocated and its fields live in SSA values. The tail of the list is where the interesting opcodes live:

 cpp
 
 
// src/deoptimizer/translation-opcode.h:60
 V(OPTIMIZED_OUT, 0) \
 V(LITERAL, 1) \
 V(REGISTER, 1) \
 V(TAGGED_STACK_SLOT, 1) \
 V(UINT32_REGISTER, 1) \
 V(UINT32_STACK_SLOT, 1) \
 V(UPDATE_FEEDBACK, 2) \
 V(MATCH_PREVIOUS_TRANSLATION, 1)

The literal array next to it holds the constants - the Name objects, the Map objects, the doubles that were folded into the code.

The clever bit: MATCH_PREVIOUS_TRANSLATION

A function with 200 deopt points does not have 200 independent recipes. Most of the frame looks the same at every deopt point - only a handful of locals differ. V8 exploits that.

FrameTranslationBuilder writes out a “basis” translation in full. When the next translation matches the basis instruction-for-instruction, it does not write those instructions again; it writes a single count:

 cpp
 
 
// src/deoptimizer/frame-translation-builder.cc:135
void FrameTranslationBuilder::FinishPendingInstructionIfNeeded() {
 if (matching_instructions_count_) {
 total_matching_instructions_in_current_translation_ +=
 matching_instructions_count_;

 // There is a short form for the MATCH_PREVIOUS_TRANSLATION instruction
 // because it's the most common opcode: rather than spending a byte on the
 // opcode and a second byte on the operand, we can use only a single byte
 // which doesn't match any valid opcode.
 const int kMaxShortenableOperand =
 std::numeric_limits<uint8_t>::max() - kNumTranslationOpcodes;
 if (matching_instructions_count_ <= kMaxShortenableOperand) {
 contents_.push_back(kNumTranslationOpcodes +
 matching_instructions_count_);
 } else {

So the encoding is: one byte whose value is past the end of the opcode range, and whose value minus the opcode count is the number of instructions to copy verbatim from the previous translation. One byte can therefore stand for up to 255 - kNumTranslationOpcodes identical instructions. For a function whose frame layout is stable across hundreds of deopt points, that is the difference between a few hundred bytes of deopt data and a few tens of kilobytes.

There is a second layer of cleverness. The builder only keeps the basis translation if the new translation reused more than three quarters of it:

 cpp
 
 
// src/deoptimizer/frame-translation-builder.cc:112
 if (!match_previous_allowed_ ||
 total_matching_instructions_in_current_translation_ >
 instruction_index_within_translation_ / 4 * 3) {
 // Use the existing basis translation.
 distance_from_last_start = start_index - index_of_basis_translation_start_;
 match_previous_allowed_ = true;
 } else {
 // Abandon the existing basis translation and write a new one.

Otherwise the sharing is not paying for itself and it writes a fresh basis. This is a classic time-space trade: share aggressively, but bail out when the sharing stops working.

The reason code is not in the translation

Here is the detail that surprises people. The DeoptimizeReason - the thing that tells you why the deopt happened, kWrongMap, kNotASmi, kArrayLengthChanged - is not stored in the deopt data at all. It is stored in the relocation info of the code object, as a RelocInfo entry of mode DEOPT_REASON at the deopt point’s PC:

 cpp
 
 
// src/deoptimizer/deoptimizer.cc:3311
Deoptimizer::DeoptInfo Deoptimizer::ComputeDeoptInfo(Tagged<Code> code,
 Address pc) {
 CHECK(code->instruction_start() <= pc && code->instruction_end());
 SourcePosition position = SourcePosition::Unknown();
 DeoptimizeReason reason = DeoptimizeReason::kUnknown;

The walk at the bottom of that function scans reloc info for DEOPT_REASON, DEOPT_ID, DEOPT_SCRIPT_OFFSET and DEOPT_INLINING_ID at exactly the PC of the deopt.

The reason for this split is cost. There are 68 deopt reasons - the count is computed from the list itself, as kDeoptimizeReasonCount:

 cpp
 
 
// src/deoptimizer/deoptimize-reason.h:20
#define DEOPTIMIZE_REASON_LIST(V) \
 DEOPTIMIZE_IN_BUILTIN_REASON_LIST(V) \
 V(ArrayBufferWasDetached, "array buffer was detached or immutable") \
 V(ArrayLengthChanged, "the array length changed") \
 V(BigIntTooBig, "BigInt too big") \
 V(CouldNotGrowElements, "failed to grow elements store") \
 V(CowArrayElementsChanged, "copy-on-write array's elements changed") \
 V(DeoptimizeNow, "%_DeoptimizeNow") \
 V(DivisionByZero, "division by zero") \
 V(GreaterThanMaxFastElementArray, \
 "length is greater than the maximum for fast elements array") \
 V(Hole, "hole") \
 V(HoleOrUndefined, "hole or undefined") \

and the tail of the list is where the interesting ones live:

 cpp
 
 
// src/deoptimizer/deoptimize-reason.h:93
 V(WrongCallTarget, "wrong call target") \
 V(WrongConstructor, "wrong call target constructor") \
 V(WrongEnumIndices, "wrong enum indices") \
 V(WrongFeedbackCell, "wrong feedback cell") \
 V(WrongInstanceType, "wrong instance type") \
 V(WrongMap, "wrong map") \
 V(WrongMapDynamic, "map changed during operation") \
 V(WrongName, "wrong name") \
 V(WrongValue, "wrong value")

Storing one of those per deopt point in the hot translation stream would bloat it. Putting it in reloc info means the reason is only ever read by --trace-deopt, by the debugger, or by the profiler - and the compiler even makes that optional, recording the reason only when source positions are on or when the reason is one of the OSR-related ones that other code inspects:

 cpp
 
 
// src/compiler/backend/code-generator.cc:199
 // RecordDeoptReason has to be right after the call so that the deopt is
 // associated with the correct pc.
 if (info()->source_positions() ||
 AlwaysPreserveDeoptReason(deoptimization_reason)) {
 masm()->RecordDeoptReason(deoptimization_reason, exit->node_id(),
 exit->pos(), deoptimization_id);
 }

Materialized objects: the arguments marker

One more piece of machinery deserves a look, because it explains a piece of V8 that looks like a bug until you see it.

The interpreter expects the arguments object in a specific stack slot to be a real JSArgumentsObject. The optimizer, however, often knows that the arguments object is not used, so it does not materialize it - it leaves a placeholder in the slot. The placeholder is a special root object called the arguments marker.

If a deopt happens and the interpreter frame needs the real arguments object, V8 cannot create it during the deopt - allocating during a deopt is forbidden, because the deopt runs in a context where the heap is not sweepable. So the object is materialized later, and until then the slot holds the marker.

The MaterializedObjectStore is the side table that remembers what was materialized for which frame:

 cpp
 
 
// src/deoptimizer/materialized-object-store.cc:26
void MaterializedObjectStore::Set(
 Address fp, DirectHandle<FixedArray> materialized_objects) {
 std::optional<uint32_t> index = StackIdToIndex(fp);
 if (!index.has_value()) {
 index = base::checked_cast<uint32_t>(frame_fps_.size());
 frame_fps_.push_back(fp);
 }

 DirectHandle<FixedArray> array = EnsureStackEntries(*index + 1);
 array->set(*index, *materialized_objects);
}

It is keyed by frame pointer, and Remove compacts the array by shifting entries down, which is why it is O(n) on removal but O(1) on lookup. The values themselves are stored in a FixedArray that lives in a heap root, so they survive the GC that may run between materialization and deopt.

The translation opcodes ARGUMENTS_ELEMENTS, ARGUMENTS_LENGTH and REST_LENGTH are what ask for the marker to be resolved. And the deoptimizer has a separate list for them:

 cpp
 
 
// src/deoptimizer/deoptimizer.cc:3214
void Deoptimizer::QueueValueForMaterialization(
 Address output_address, Tagged<Object> obj,
 const TranslatedFrame::iterator& iterator) {
 if (obj == ReadOnlyRoots(isolate_).arguments_marker()) {
 values_to_materialize_.push_back({output_address, iterator});
 }
}

MaterializeHeapObjects then walks that list and writes the real values into the output frames. It is also where the feedback vector is patched back in, because the optimized code may have used a feedback vector that the interpreter frame needs to find:

 cpp
 
 
// src/deoptimizer/deoptimizer.cc:3186
 for (auto& fbv_materialization : feedback_vector_to_materialize_) {
 DirectHandle<Object> closure = fbv_materialization.value_->GetValue();
 DCHECK(IsJSFunction(*closure));
 Tagged<Object> feedback_vector =
 Cast<JSFunction>(*closure)->raw_feedback_cell()->value();
 CHECK(IsFeedbackVector(feedback_vector));
 *(reinterpret_cast<Address*>(fbv_materialization.output_slot_address_)) =
 feedback_vector.ptr();
 }

The deopt exit itself

All of the above is driven by generated code. The compiler emits a call to one of three builtins, and the builtin spills the machine state into a FrameDescription:

 cpp
 
 
// src/builtins/x64/builtins-x64.cc:5157
void Generate_DeoptimizationEntry(MacroAssembler* masm,
 DeoptimizeKind deopt_kind) {
 __ ExitSandbox();
 // This builtins transitions out of sandboxed execution mode.
 __ SetSandboxingModeForCurrentBuiltin(CodeSandboxingMode::kUnsandboxed);

and then walks the translation:

 cpp
 
 
// src/deoptimizer/deoptimizer.cc:1651
void Deoptimizer::DoComputeOutputFrames() {
 // When we call this function, the return address of the previous frame has
 // been removed from the stack by the DeoptimizationEntry builtin, so the
 // stack is not iterable by the StackFrameIteratorForProfiler.

The output frames are dispatched back into the interpreter. Whether the interpreter resumes at the current bytecode or the next one depends on the deopt kind:

 cpp
 
 
// src/deoptimizer/deoptimizer.cc:2093
 const bool advance_bc =
 (!is_topmost || (deopt_kind_ == DeoptimizeKind::kLazy)) &&
 !goto_catch_handler;
 const bool restart_frame = goto_catch_handler && is_restart_frame();
 Tagged<Code> dispatch_builtin =
 builtins->code(DispatchBuiltinFor(advance_bc, restart_frame));

Trade-offs

What it buys. Speculation. Without a working deopt, TurboFan could only optimize for shapes it could prove, and JavaScript programs change shape all the time. The deopt is what makes aggressive speculation safe, and safe speculation is most of V8’s performance story.

What it costs.

Code size. Every deopt point needs a translation entry, and the translation is a byte stream per frame per deopt point. The MATCH_PREVIOUS_TRANSLATION trick is what keeps this bounded.
The deopt itself is slow. Rebuilding a frame means allocating FrameDescription objects, walking the translation, and copying values around. A deopt in a hot loop is a performance cliff.
Deopt loops. If the recompiled code makes the same wrong assumption again, you deopt again. The feedback vector has a was_once_deoptimized flag, and kInvocationCountBeforeStableDeoptSentinel records that a function deoptimized, so the compiler can use it as a “blanked bailout” for optimizations that are not deopt-loop free.
The soft path is not free either. Marking code for deoptimization requires a stack walk of every thread, and zapping the deopt exits means the code can never be re-entered.

The bottom line

A deopt is a reconstruction from a recipe. TurboFan emits, for every point where it might have to bail out, a byte-coded description of how to rebuild the interpreter frame that the optimizer replaced - where each value lives, what type it is, and which of them the optimizer deleted entirely. The runtime, on a failed guard, walks that recipe against the spilled registers and reconstructs a frame the interpreter can continue from.

The mental model to keep is that the translation stream is the inverse of the optimizer. Every transformation TurboFan applies - register allocation, inlining, escape analysis, constant folding - has a corresponding opcode that undoes it. OPTIMIZED_OUT undoes a deleted local. CAPTURED_OBJECT undoes an allocation that never happened. DOUBLE_REGISTER says “this was a double, and the interpreter wants it boxed”.

The thing people get wrong

“Deoptimization means the JIT failed.” It does not. A deopt means the JIT was right to check. The optimizer wrote a guard, the guard fired, and V8 recovered - correctly, and in a few microseconds - from a situation that, handled badly, would have been a wrong answer or a crash.

The more interesting failure mode is the opposite one: a function that deopts over and over. That is a compilation problem, not a deopt problem.

If you are profiling and you see deopts, do not go looking for a bug in the deoptimizer. Go and look at the shape of your data. The deopt is V8 telling you, in as many words, that your objects do not have the shape the optimizer assumed.

Deopt on Opensource internals