JSONRepair

Why JSON.stringify Drops Undefined and Functions

If you wonder why JSON.stringify removes undefined and functions, here is the short version: JSON has no way to write either one, so the serializer quietly leaves them out instead of throwing. No error, no warning, and a payload that looks complete until the receiving side notices a field is gone.

Here is the version of this bug most people meet first. You log an object, everything looks right, then you serialize it and a field vanishes:

const user = { id: 1, name: "Ana", email: undefined };
JSON.stringify(user);
// {"id":1,"name":"Ana"}

The email property is not set to null. It is not set to an empty string. It is gone, as if it never existed. The same thing happens to functions and to symbols. Put any of the three in an object and stringify drops the whole property. That behavior is not a quirk of one library or one version of JavaScript. It follows from the JSON grammar itself, which allows exactly six kinds of value: strings, numbers, booleans, null, arrays, and objects. Undefined is not on the list. Functions are not on the list. Symbols are not on the list. A serializer that promised to write JSON cannot write what the format cannot hold, so it makes a choice, and the choice it makes is silence.

Arrays get a different choice, and the difference matters. Inside an array, dropping an item would shift every later item one position to the left, so stringify substitutes null instead:

JSON.stringify([1, undefined, function() {}, Symbol("x")]);
// [1,null,null,null]

That keeps positions aligned, which is the right call for ordered data, but it means the same input value produces two different outputs depending on where it sits. An object property disappears. An array slot becomes null. If you have ever debugged a payload where a field was missing in one place and null in another, this split is often the explanation.

Why JSON.stringify removes undefined and functions instead of erroring

It helps to compare this with the two cases where stringify does throw. Circular references throw, because there is no honest output for them. BigInt values throw, because the spec gives them no representation and the committee chose an error over a guess. Undefined and functions get the quiet treatment instead, and I think the reason is practical: dropping a property is usually harmless, and throwing on every object with an optional field would make the function unusable for everyday logging and API work. The tradeoff is that the quiet behavior hides real bugs, which is why it surprises people the first time they meet it.

There is one more quiet case worth knowing. Stringify a top level undefined, function, or symbol and you do not get a string at all. You get the JavaScript value undefined back, not text:

JSON.stringify(undefined);   // undefined, not "undefined"
JSON.stringify(function() {}); // undefined

That bites when you pass the result straight into something expecting a string, like localStorage.setItem, which will store the literal text "undefined" and hand you a confusing parse error later.

The replacer fix, and when to use it

The fix is the replacer, the second argument to JSON.stringify. A replacer runs on every key and value before the text is built, so it is the one place where you can decide what unrepresentable values become:

const cleaned = JSON.stringify(user, (key, value) => {
  if (value === undefined) return null;
  if (typeof value === "function") return "[Function]";
  return value;
});

Which replacement you pick depends on what the receiver needs. Null is the honest choice when "no value" is all the receiver needs to know. A marker string like "[Function]" is better for debug logs, where you want to see that something was there. What you should not do is pick a marker and then forget it, because the receiver will treat "[Function]" as an ordinary string, and a downstream consumer that expects a number or an object will break in a new way. Document the convention next to the schema, the same way you would document a null convention for NaN.

There is a second, subtler trap here, and it is the one I would actually worry about in production. In a PATCH request, many APIs treat a missing field as "leave it alone" and an explicit null as "clear it." If your client builds a PATCH body from an object with undefined fields and stringifies it, those fields silently drop out, and the API leaves them alone. That is usually what you wanted, but only by accident. If someone later changes the client to send null for cleared fields, the same endpoint starts wiping data. The serializer is not the bug in that story. The bug is that two meanings, "unchanged" and "cleared", were both riding on the difference between a missing key and a null, and nobody wrote it down.

My rule for this is simple. If a value can be undefined in your code, decide before serialization what it means in the payload, and encode that decision explicitly. Use null for cleared, omit the key deliberately for unchanged, and use a replacer so the decision lives in one place instead of depending on whatever each call site happened to pass. Objects that reach stringify should already be payload shaped, with no functions, symbols, or undefined values left to the serializer's discretion.

Paste your broken JSON into the repair tool and it will show a valid replacement before you send the payload anywhere else.

Frequently asked questions

Why does JSON.stringify remove undefined values?

JSON has no undefined value. The grammar allows strings, numbers, booleans, null, arrays, and objects only, so the serializer omits undefined object properties rather than writing something invalid.

What happens to functions in JSON.stringify?

Function properties in objects are dropped, and function values in arrays become null. If you need a trace of them, use a replacer function to convert them to a string first.

Why does JSON.stringify return undefined for undefined input?

When the top level value itself cannot be represented, stringify returns the JavaScript value undefined instead of a string. Passing that result to storage or a network call produces confusing errors later.

How do I keep undefined fields as null?

Pass a replacer as the second argument to JSON.stringify that returns null whenever it sees undefined. That turns dropped properties into explicit nulls.

Does JSON.stringify drop symbol values too?

Yes. Symbols behave like functions: dropped from objects, converted to null in arrays, and they return undefined at the top level.

Get one practical guide a week: subscribe to the newsletter for new guides.

Related reading: How to Fix the BigInt Error in JSON.stringify · How to Fix Converting Circular Structure to JSON · How to Fix NaN and Infinity in JSON