undefined inside the engine

One undefined, many ways to get it

You know undefined from everyday JavaScript. This lesson shows how a JavaScript engine stores it. An engine is the program that runs your code. We use V8, the engine inside Chrome and Node.js. Every fact here was checked in Node 22, which uses V8 version 12.4.

Inside V8, there is exactly one undefined. V8 makes it once, when it starts. V8 calls a few special built-in values oddballs, and undefined is one of them. A variable that holds undefined only stores a pointer to it. A pointer is a memory address: it says where a value is. So getting undefined never makes a new value.

1const fromIdentifier = undefined;2const fromVoid = void 0;3function noReturn() {}4 5console.log(fromIdentifier === fromVoid);6console.log(noReturn());7console.log(Object.is(fromIdentifier, undefined));

Line 1 stores undefined by name. Line 2 uses the void operator: void runs the expression after it and always gives undefined. Line 3 makes a function with no return.

• Line 5 prints true: the first two ways give the same value.
• Line 6 prints undefined: a function that reaches its end without return gives undefined.
• Line 7 prints true. Object.is checks whether two values are exactly the same value.

If you want the everyday rules for undefined first, read undefined. This lesson also uses the idea of a tagged pointer: a stored pointer with a small mark that says "this is a pointer, not a small number". The Tagged values lesson explains it.

One more detail about the test machine. Node 22 here runs V8 12.4.254.21 without pointer compression, a trick that stores pointers in fewer bytes. Chrome uses newer V8 versions, usually with pointer compression and the sandbox, a fence that limits which memory V8 can touch. So memory addresses and object sizes differ. What stays the same: the names of V8's types, the names of its instructions, and the rules in its source code.

Where V8 keeps undefined

V8 is written in the C++ language, and its source code is public. So we can read how it builds undefined. The file oddball.h describes oddballs. Its comment says that four values are oddballs: null, undefined, true, and false.

Each oddball stores a few ready-made answers, so V8 never has to work them out again:

• to_number_raw and to_number: the value as a number. For undefined, that is NaN.
• to_string: the value as a string, "undefined".
• type_of: what typeof gives, also "undefined".
• kind: a small number that says which oddball this is. For undefined, it is kUndefined = 4.

V8 also gives every object a map: V8's record of a value's type and shape. undefined gets its own map, undefined_map. That map is marked undetectable. This mark means "treat this value like undefined in loose checks such as x == null". The map of null has the same mark.

1%DebugPrint(undefined);

%DebugPrint is a special V8 helper. It prints what V8 stores for a value. It only works when you start Node with node --allow-natives-syntax, so this block can't run on this page. The lesson's test runs it and checks the parts that are the same on every run:

• [Oddball] in ReadOnlySpace: #undefined: it is the oddball, kept in read-only space.
• type: ODDBALL_TYPE: the map says its type is oddball.
• stable_map, undetectable, and non-extensible: the map never changes, has the undetectable mark, and can't get new properties.
• prototype: <null>: it has no prototype to look things up in.

You'll see the same kind of map again in null inside the engine. That is why both null and undefined are "undetectable" inside V8.

1// V8 12.4: src/objects/oddball.h2// The Oddball describes objects null, undefined, true, and false.3// [to_number_raw]: Cached raw to_number computed at startup.4// [to_string]: Cached to_string computed at startup.5// [to_number]: Cached to_number computed at startup.6// [typeof]: Cached type_of computed at startup.7static constexpr uint8_t kUndefined = 4;8 9// V8 12.4: src/heap/setup-heap-internal.cc10InitializePartialMap(undefined_map, meta_map, ODDBALL_TYPE, sizeof(Undefined));11roots.undefined_map()->set_is_undetectable(true);12Oddball::Initialize(isolate(), factory->undefined_value(), "undefined",13                    factory->nan_value(), "undefined", Oddball::kUndefined);

These lines come from two V8 files. In plain words, the highlighted lines say:

1. Line 2: the oddball type covers null, undefined, true, and false.
2. Line 7: the kind number for undefined is 4.
3. Line 10: make a map called undefined_map, with the type ODDBALL_TYPE.
4. Line 11: mark that map as undetectable.
5. Lines 12 and 13: fill in the ready-made answers: the string "undefined", the number NaN, the typeof text "undefined", and the kind.

The second file, setup-heap-internal.cc, builds these maps and values when V8 starts. The debug output above shows that this Node build keeps undefined in read-only space. V8's read-only serializer saves that read-only memory into the startup snapshot: a saved copy of memory that V8 loads every time it starts.

Other engines store undefined differently. The next block shows two of them. JavaScriptCore is Safari's engine, and SpiderMonkey is Firefox's engine.

1// JavaScriptCore runtime/JSCJSValue.h2// False: 0x063// True:  0x074// Undefined: 0x0a5// Null: 0x026static constexpr int32_t OtherTag       = 0x2;7static constexpr int32_t UndefinedTag   = 0x8;8static constexpr int32_t ValueUndefined = OtherTag | UndefinedTag;9 10// SpiderMonkey js/public/Value.h11enum JSValueType : uint8_t {12  JSVAL_TYPE_UNDEFINED = 0x03,13  JSVAL_TYPE_NULL = 0x04,14};15JSVAL_TAG_UNDEFINED = JSVAL_TAG_MAX_DOUBLE | JSVAL_TYPE_UNDEFINED;

Numbers that start with 0x are written in hexadecimal (base 16). For example, 0x0a is 10.

• In JavaScriptCore's JSCJSValue.h, the comment on line 4 lists Undefined: 0x0a. Line 8 builds it as ValueUndefined = OtherTag | UndefinedTag. This is not a pointer. The stored value itself is the number 0x0a.
• In SpiderMonkey's Value.h, line 12 gives undefined the type number JSVAL_TYPE_UNDEFINED = 0x03. Line 15 turns that into a mark called JSVAL_TAG_UNDEFINED.

So the JavaScript value is the same in every engine. Only the way it is stored in memory is different. The table below has one row per value or engine. Read each row as: "this is how it is stored, and this is the proof."

Where bytecode gets undefined

Before V8 runs a function, it turns it into bytecode: a list of small, simple instructions. V8's interpreter, called Ignition, runs these instructions one at a time. Each instruction has a short name. For example, LdaUndefined means "load undefined".

The instructions in this lesson use two kinds of slots:

• The accumulator: one special slot that holds the value the interpreter is working on right now.
• Registers: numbered slots for local variables, written r0, r1, and so on.

Names that start with Lda load a value into the accumulator. Return gives back whatever is in the accumulator. The lesson's test asks Node to print the bytecode of four small functions. All four print LdaUndefined, then Return:

• a bare return;
• a function that reaches its end without return
• return void 0
• return undefined, when undefined means the usual global one

1return;                 LdaUndefined, Return2fall off the end       LdaUndefined, Return3return void 0          LdaUndefined, Return4return undefined       LdaUndefined, Return5let x; return x        LdaUndefined, Star0, Return6x === undefined        Ldar, TestUndefined, Return

Each row shows a piece of code on the left and its instructions on the right. "Fall off the end" means the function reaches its last line without a return.

1. Lines 1 to 4: load undefined into the accumulator, then return it.
2. Line 5: load undefined, then Star0 stores it in register r0, which holds x. Then return it.
3. Line 6: Ldar loads x into the accumulator. TestUndefined checks whether it is undefined and leaves true or false. Then return that answer.

There is one exception. You are allowed to make a local variable called undefined. Then the name means your variable, not the real undefined. We say the local variable shadows the global one. So function f() { let undefined = 5; return undefined; } returns 5. Its bytecode uses LdaSmi (load a small whole number), Star0, and later Ldar r0. It never loads the real undefined.

A let or const variable can't be read before its line runs. Reading it too early throws a ReferenceError. The time before the line runs is called the temporal dead zone, or TDZ. V8 marks a variable in its TDZ with a different value: the hole. For const r = y; let y = 1;, Node prints these instructions:

• LdaTheHole: load the hole.
• Star1: store it in register r1, the slot for y.
• ThrowReferenceErrorIfHole: when the code reads y, throw a ReferenceError if the slot still holds the hole.

The hole lets V8 tell "not set up yet" apart from the real undefined. You'll learn more about the hole below.

Registers and missing arguments

When a function is called, V8 gives that call a stack frame: a block of memory for that one call. The registers live in the stack frame. Before the first instruction runs, V8 runs a short piece of setup code called the interpreter entry trampoline. One of its jobs is to put undefined into every register.

V8's source has this setup code for each kind of processor. The block shows two: x64 (most desktop and laptop computers) and arm64 (phones and newer Macs). Both say the same thing.

1// V8 12.4: src/builtins/x64/builtins-x64.cc2// If ok, push undefined as the initial value for all register file entries.3__ LoadRoot(kInterpreterAccumulatorRegister, RootIndex::kUndefinedValue);4__ Push(kInterpreterAccumulatorRegister);5// The accumulator is already loaded with undefined.6 7// V8 12.4: src/builtins/arm64/builtins-arm64.cc8// If ok, push undefined as the initial value for all register file entries.9__ LoadRoot(kInterpreterAccumulatorRegister, RootIndex::kUndefinedValue);10__ PushMultipleTimes(kInterpreterAccumulatorRegister, x11);11// The accumulator is already loaded with undefined.

In plain words, the highlighted lines say:

1. Lines 2 and 8: the comment says "push undefined as the starting value for every register".
2. Lines 3 and 9: LoadRoot fetches undefined. A root is a value the engine always keeps ready, such as undefined.
3. Lines 4 and 10: push that value into the register slots.
4. Lines 5 and 11: the accumulator now holds undefined too.

So every register starts as undefined. A register never starts with leftover data from earlier code.

Now the missing arguments. A function's parameters are the names in its brackets, like name, role, city. What happens if you pass fewer values than that? The missing parameters become undefined. V8's arguments adaptor frame article explains how. Before V8 version 8.9, V8 built an extra stack frame to handle this. Since 8.9, that extra frame is gone. The call setup fills the missing parameters with undefined itself. In the x64 source, that call setup code is named InvokePrologue.

1// V8 12.4: src/codegen/x64/macro-assembler-x64.cc2// Underapplication. Move the arguments already in the stack, including the3// receiver and the return address.4// Fill remaining expected arguments with undefined values.5LoadRoot(kScratchRegister, RootIndex::kUndefinedValue);6movq(Operand(r8, expected_parameter_count, times_system_pointer_size, 0),7     kScratchRegister);

In plain words, the highlighted lines say:

1. Line 4: the comment says "fill the remaining expected arguments with undefined".
2. Line 5: fetch undefined into a spare register.
3. Lines 6 and 7: write it into the slot of the next missing parameter. V8 repeats this for each missing one.

1function makeBadge(name, role, city) {2  const stackSlots = [name, role, city];3  return stackSlots.map(String).join(" | ");4}5 6console.log(makeBadge("Ada"));Run

Press Step to walk through the replay. It calls makeBadge("Ada") with one value. Then name is "Ada", and role and city are undefined. These values come from really running the function. The frame drawing beside the code is a simple model, not real engine memory.

The hole is not undefined

You met the hole in the TDZ example. The hole is a marker: a special value V8 uses only inside itself, to mean "nothing is here yet" or "nothing is here at all". Your code never gets the hole itself. When your code reads a slot that holds the hole, V8 follows a rule first. The rule either gives a normal result or throws an error.

In V8 12.4, the hole is not an oddball. It has its own type, Hole. V8 also makes several different holes, one for each job. Here are the ones in the source below:

• the_hole_value: the main hole, used for gaps in arrays and for the TDZ.
• property_cell_hole_value, hash_table_hole_value, promise_hole_value, uninitialized_value, arguments_marker, optimized_out, and stale_register: more holes, each used by one part of V8.

1// V8 12.4: src/objects/hole.h2class Hole : public HeapObject {3  // Holes store NaN at the HeapNumber value offset for optimized code.4  DECL_FIELD_OFFSET_TQ(RawNumericValue, HeapObject::kHeaderSize, "float64")5};6 7// V8 12.4: src/heap/setup-heap-internal.cc8Hole::Initialize(isolate(), factory->the_hole_value(), factory->hole_nan_value());9set_property_cell_hole_value(*factory->NewHole());10set_hash_table_hole_value(*factory->NewHole());11set_promise_hole_value(*factory->NewHole());12set_uninitialized_value(*factory->NewHole());13set_arguments_marker(*factory->NewHole());14set_optimized_out(*factory->NewHole());15set_stale_register(*factory->NewHole());

In plain words, the highlighted lines say:

1. Line 2: Hole is its own kind of object. It is not an Oddball.
2. Line 8: set up the main hole, the_hole_value.
3. Lines 9 to 15: make one more separate hole for each of the other jobs.

Arrays with gaps

You can write an array with a gap: [1, , 3]. The two commas with nothing between them leave index 1 empty. An array with gaps is called a sparse array. V8 keeps the hole in the empty slot.

V8 also labels every array with an elements kind: what sort of items it holds, and whether it may have gaps. Two labels matter here:

• HOLEY_SMI_ELEMENTS: small whole numbers, and there may be gaps. (A Smi is a small whole number.)
• PACKED_ELEMENTS: any values, and no gaps. Packed means every index has an item.

The Elements kinds lesson covers all the labels.

1%DebugPrint([1, , 3]);2%DebugPrint([1, undefined, 3]);

In Node 22, line 1 prints HOLEY_SMI_ELEMENTS, and the empty slot shows as <the_hole_value>. Line 2 prints PACKED_ELEMENTS. In [1, undefined, 3], index 1 is a real item that holds undefined, so there is no gap.

1const sparse = [1, , 3];2const explicit = [1, undefined, 3];3 4console.log(1 in sparse, 1 in explicit);5console.log(sparse[1], explicit[1]);6console.log(Object.keys(sparse).join(","));7console.log(Object.keys(explicit).join(","));8sparse.forEach((value, index) => console.log("sparse", index, String(value)));9explicit.forEach((value, index) => console.log("explicit", index, String(value)));

Line 1 makes an array with a gap. Line 2 makes an array that holds undefined at index 1. Then:

• Line 4 prints false true. The in operator asks "does this array have an item at this index?" sparse has none at index 1; explicit has one.
• Line 5 prints undefined undefined. A plain read can't tell the two apart.
• Lines 6 and 7 print 0,2 and 0,1,2. Object.keys lists the indexes that have items, so it skips the gap.
• Lines 8 and 9: forEach also skips the gap. It prints two lines for sparse and three for explicit.

Why does reading a gap give undefined? Because a gap means "no item here", and JavaScript then looks somewhere else. Every array has a prototype: a shared object it falls back on, Array.prototype. When an array has no item at an index, JavaScript looks for that index in Array.prototype, then in Object.prototype. This line of fallback objects is called the prototype chain. Only if nothing is found there does the read give undefined.

1const sparse = [1, , 3];2const hadOwn = Object.prototype.hasOwnProperty.call(Array.prototype, 1);3const oldValue = Array.prototype[1];4 5try {6  Array.prototype[1] = "surprise";7  console.log(sparse[1]);8} finally {9  if (hadOwn) {10    Array.prototype[1] = oldValue;11  } else {12    delete Array.prototype[1];13  }14}

Line 1 makes the array with a gap. Lines 2 and 3 remember whether Array.prototype already had an item 1, and what it was. Normally it has none. Line 6 puts "surprise" at Array.prototype[1]. Line 7 reads sparse[1] and prints surprise: the gap found the item in the prototype.

A finally block always runs after try. Here, lines 9 to 13 put Array.prototype back the way it was, so later code on this page isn't affected.

Looking through the prototype chain for every gap would be slow. So V8 keeps a protector: a yes-or-no flag that says "nobody has put numbered items on Array.prototype or Object.prototype". While the flag is true, fast code can skip the prototype lookup. The flag is called the NoElements protector. Once someone adds a numbered item there, V8 sets the flag to false and never sets it back.

1console.log(%NoElementsProtector());2const hadOwn = Object.prototype.hasOwnProperty.call(Array.prototype, 1);3const oldValue = Array.prototype[1];4try {5  Array.prototype[1] = "prototype element";6  console.log(%NoElementsProtector());7} finally {8  if (hadOwn) Array.prototype[1] = oldValue;9  else delete Array.prototype[1];10}

%NoElementsProtector() is another special helper that needs node --allow-natives-syntax. Line 1 prints true. Line 5 adds an item at Array.prototype[1]. Line 6 prints false. Lines 8 and 9 put the prototype back. The name comes from V8's protectors.h, where NoElements becomes NoElementsProtector.

1const sparse = [1, , 3];Run2const explicit = [1, undefined, 3];3console.log(1 in sparse);4console.log(1 in explicit);5console.log(sparse[1]);6const hadOwn = Object.prototype.hasOwnProperty.call(Array.prototype, 1);7const oldValue = Array.prototype[1];8try {9  Array.prototype[1] = "surprise";10  console.log(sparse[1]);11} finally {12  if (hadOwn) Array.prototype[1] = oldValue;13  else delete Array.prototype[1];14}

Press Step to walk through the replay. It reads sparse[1] twice: once before the prototype gets an item 1, and once after. The first read gives undefined. The second gives "surprise".

Missing properties

Reading a property such as receiver.missing works in steps:

1. V8 looks in the object itself. A property stored there is called an own property.
2. If it isn't there, V8 looks in the object's prototype, then in that prototype's prototype, and so on.
3. The chain ends at null. If no object had the property, the read gives undefined.

A missing variable name is different. Reading a name that was never declared throws a ReferenceError.

1const parent = { inherited: "from prototype" };2const receiver = Object.create(parent);3receiver.present = 1;4 5console.log(receiver.present);6console.log(receiver.inherited);7console.log(receiver.missing);8console.log("missing" in receiver);

Line 1 makes a parent object with one property. Line 2 uses Object.create(parent) to make a new object whose prototype is parent. Line 3 gives the new object its own property, present.

• Line 5 prints 1, found in the object itself.
• Line 6 prints from prototype, found in parent. A property found this way is inherited.
• Line 7 prints undefined. No object in the chain has missing.
• Line 8 prints false. The in operator checks the whole chain and finds nothing.

V8 makes repeated property reads fast with an inline cache: a small memory at each property read in your code. It remembers what happened last time, so the next read can skip the search. What it saves is called a handler: a short recipe for the read. One handler is named LoadNonExistent. It means "this property doesn't exist, so give undefined".

1// V8 12.4: src/ic/ic.cc2Handle<Smi> smi_handler = LoadHandler::LoadNonExistent(isolate());3handler = MaybeObjectHandle(LoadHandler::LoadFullChain(4    isolate(), lookup_start_object_map(),5    MaybeObjectHandle(isolate()->factory()->null_value()), smi_handler));6 7// V8 12.4: src/ic/accessor-assembler.cc8// This is a handler for a load of a non-existent value.9exit_point->Return(UndefinedConstant());10 11// V8 12.4: src/ic/handler-configuration.cc12Handle<Object> validity_cell = Map::GetOrCreatePrototypeChainValidityCell(13    lookup_start_object_map, isolate);14handler->set_validity_cell(*validity_cell);

In plain words, the highlighted lines say:

1. Lines 2 and 3: make a LoadNonExistent handler that covers the whole prototype chain.
2. Lines 8 and 9: this handler is for a missing property, and it gives back undefined.
3. Lines 12 and 14: attach a validity cell, a flag that stays valid only while the prototype chain doesn't change.

The global undefined can't be changed

The name undefined is also a property of the global object, globalThis. Every property has a few settings. You can read them with Object.getOwnPropertyDescriptor. The result is called a descriptor. Three of its settings matter here:

• writable: can you give the property a new value?
• enumerable: does it show up when you list an object's properties?
• configurable: can you delete it or change its settings?

For globalThis.undefined, all three are false. The language rules, ECMA-262, say so, and the lesson's test checks it.

1const descriptor = Object.getOwnPropertyDescriptor(globalThis, "undefined");2console.log(descriptor.writable, descriptor.enumerable, descriptor.configurable);3 4(function sloppyAssignment() {5  undefined = "changed";6  console.log(undefined);7})();8 9(function strictAssignment() {10  "use strict";11  try {12    undefined = "changed";13  } catch (error) {14    console.log(error.name);15  }16})();

• Lines 1 and 2 read the descriptor and print false false false.
• Lines 5 and 6 run in normal, non-strict code. The assignment on line 5 is quietly ignored, so line 6 prints undefined.
• Line 10 turns on strict mode. Now the assignment on line 12 throws, and line 14 prints TypeError.

You may see void 0 in older or generated code. In very old JavaScript, the global undefined could be changed, so careful code wrote void 0 instead. A minifier is a tool that makes code smaller, and some still write void 0 because it is shorter. Terser, a popular minifier, has an option for this called unsafe_undefined. But it isn't faster: the bytecode above is the same for void 0 and the usual undefined.

Playground: pick some code and read its bytecode

Pick one of the twelve pieces of code. The left side shows the JavaScript. The right side shows the names of its bytecode instructions, copied from real Node output. The lesson's test runs each piece again with Node's --print-bytecode --print-bytecode-filter options and checks that the names still match.

1function retVoid() { return; }2retVoid();

100  LdaUndefined201  Return

Practical use

Most everyday code doesn't need to think about oddballs. This lesson helps in three ways: you won't mix up a gap with a real undefined, you'll read performance tools more easily, and you'll write clearer code when undefined means something.

The table below turns the lesson into habits. Read each row as: "do this, like this, because of this."

• When every index should have an item, keep the array packed. Use a real undefined item only when an empty item is the point.
• In code that runs very often, don't make arrays with new Array(n), which starts full of gaps, unless measuring shows it is fine.
• Don't make local variables named undefined. It is allowed, but it confuses readers and V8's quick LdaUndefined path.
• Use void 0 only for old browsers or generated code. Modern V8 doesn't make it faster.

Common mix-ups

• "Every empty-looking slot is undefined." No. Array gaps and TDZ variables hold the hole. V8 follows a rule before your code gets a result or an error.
• "Reading a gap simply gives undefined." Not straight away. JavaScript looks in the prototype chain first, so an item there can show up.
• "void 0 is faster than undefined." No. In the cases tested here, both become the same LdaUndefined instruction.
• "A missing property and an undeclared variable are the same." No. A missing property gives undefined. An undeclared name throws a ReferenceError.
• "The addresses in Node's debug output are facts to memorize." No. Addresses and sizes change between builds. Type names and instruction names stay the same.

The table below compares five things that are easy to mix up. Read each row as: "when I have this, what is it, what does my code see, and what does V8 do?"

Each exercise is a short program. The first ones ask for one word or one output. The last one asks you to pick a kind of array. Try a guess first, then use the hints if you get stuck.

function f() { return undefined; }
f();

const sparse = [1, , 3];
const explicit = [1, undefined, 3];
console.log(1 in sparse);
console.log(1 in explicit);

function second(a, b) {
  return b;
}
console.log(second("first"));

const descriptor = Object.getOwnPropertyDescriptor(globalThis, "undefined");
console.log(descriptor.writable);

const sparse = [1, , 3];
const hadOwn = Object.prototype.hasOwnProperty.call(Array.prototype, 1);
const oldValue = Array.prototype[1];

try {
  Array.prototype[1] = "surprise";
  console.log(sparse[1]);
} finally {
  if (hadOwn) {
    Array.prototype[1] = oldValue;
  } else {
    delete Array.prototype[1];
  }
}

const packed = Array.from({ length: 3 }, (_, index) => index + 1);
const holey = new Array(3);
console.log(packed.length, 1 in packed);
console.log(holey.length, 1 in holey);

Key takeaways

• V8 has exactly one undefined: a read-only oddball made at startup. Getting undefined never makes a new value.
• The LdaUndefined instruction loads it for return;, void 0, and the usual global undefined.
• The hole is a different marker, used for array gaps and the TDZ. Your code never gets the hole itself.
• Missing properties and missing arguments both give undefined, but V8 gets there in different ways.
• Keep arrays packed and code clear. Measure before you change code for the engine's sake.

One-line definition: undefined is V8's one read-only oddball. Holes and missing lookups are paths inside V8 that may end in that value.

Up next: null inside the engine.