undefined Is Not Valid in JSON – How to Handle It

JSON defines six value types: string, number, object, array, boolean (true/false), and null. undefined is not on that list. It is a JavaScript concept that has no equivalent in the JSON specification. This causes several subtle behaviors worth understanding before you build an API or serialize data.

What JSON.stringify does with undefined

When you serialize a JavaScript object using JSON.stringify(), properties with an undefined value are silently dropped from the output:

const user = {
  name: "Alice",
  email: undefined,   // will be dropped
  age: 30
};

console.log(JSON.stringify(user));
// Output: {"name":"Alice","age":30}
// "email" is gone entirely

This is often surprising. The object had three properties but the JSON has two — and no error was thrown. If the receiver expects an email key, it will get undefined when it reads data.email in JavaScript, or an equivalent missing-key behavior in other languages.

undefined in arrays becomes null

Arrays behave differently. Because dropping an array element would change the array's length, JSON.stringify() converts undefined array elements to null instead:

JSON.stringify([1, undefined, 3]);
// Output: "[1,null,3]"

A top-level undefined returns undefined from stringify

JSON.stringify(undefined);
// Output: undefined (not a string — the function returns the JS value undefined)

null vs undefined in JSON

null is valid JSON. Use it when you want to explicitly represent the absence of a value in a way that survives serialization:

const user = {
  name: "Alice",
  email: null,  // explicitly absent — survives JSON.stringify
  age: 30
};

console.log(JSON.stringify(user));
// Output: {"name":"Alice","email":null,"age":30}

If you are designing an API, use null for optional fields that have no current value. This makes the structure predictable — consumers always receive the key and know it is intentionally absent.

How to handle undefined before serializing

If you receive data that might contain undefined values and need to serialize it safely, you have a few options:

Option 1 — replace undefined with null explicitly

const clean = Object.fromEntries(
  Object.entries(obj).map(([k, v]) => [k, v === undefined ? null : v])
);

Option 2 — use the JSON.stringify replacer function

const json = JSON.stringify(obj, (key, value) =>
  value === undefined ? null : value
);

Option 3 — remove undefined properties intentionally

If omitting the key is the correct behavior, rely on JSON.stringify()'s default behavior — it will drop undefined properties automatically. This is correct when the key is genuinely optional and receivers are expected to use a default when it is missing.

Parsing JSON with undefined

You cannot include the literal text undefined in a JSON string and expect it to parse:

JSON.parse('{"name": undefined}');
// SyntaxError: Unexpected token u in JSON at position 9

If you see this error, the data was not properly serialized. The source should have used null instead of undefined, or omitted the key entirely.

The object-vs-array asymmetry that surprises people

The trickiest part of undefined in JSON is that it behaves differently depending on where it sits. In an object, a property whose value is undefined is dropped entirely — {a: 1, b: undefined} serializes to {"a":1}, and the key vanishes. In an array, positions matter, so undefined can't just disappear without shifting every later index; instead it's replaced with null. So [1, undefined, 3] becomes [1,null,3]. This single rule explains a whole class of bugs: an object silently loses a field, while an array silently gains a null. If your downstream code assumes every array element is a real value, that injected null is exactly the kind of thing that later throws "cannot read properties of null."

Designing APIs around present, null, and absent

Because of this behaviour you effectively have three states to reason about: a key with a real value, a key explicitly set to null, and a key that's absent. Decide deliberately which one means what in your API. A common convention is that null means "known to have no value" while an absent key means "not provided / unchanged" — important for PATCH endpoints, where sending null should clear a field but omitting it should leave the field untouched. If you want undefined fields preserved as explicit nulls rather than dropped, normalize them before serializing (for example, map undefined to null in a replacer function). When you're checking what actually crossed the wire, paste the payload into the JSON Validator to see the real, parsed structure.