JSON undefined Is Not Valid — Why Keys Silently Disappear and How to Stop It

The JSON specification, defined in RFC 8259, enumerates exactly six value types: string, number, object, array, true, false, and null. The word undefined does not appear anywhere in the spec. This is not an oversight — JSON was designed as a language-independent format, and undefined is a concept specific to JavaScript and a handful of other languages. Languages like Python, Go, Java, and Rust have no equivalent concept.

When JSON.stringify encounters an object property whose value is undefined, it takes the only action that preserves spec compliance: it omits the key entirely. Including the key with a value of undefined is not possible because undefined is not a JSON value. Including it with null would silently change the meaning. So the key vanishes. No error, no warning, no indication that anything was lost.

Array slots behave differently. Because arrays preserve positional structure, omitting a slot would renumber everything after it and break length assumptions. Instead, JSON.stringify replaces undefined array elements with null. So JSON.stringify([1, undefined, 3]) produces '[1,null,3]' — the slot is filled with the closest JSON equivalent of nothing.

Calling JSON.stringify(undefined) directly, without wrapping it in an object or array, returns the JavaScript value undefined — not the string 'undefined', not 'null', not anything. If you assign this result to a variable and use it as a fetch body, you end up with undefined as the body, which is effectively no body at all. This is particularly insidious in test code where developers check the type of the serialization result and expect a string.

Understanding this behavior means accepting that JSON.stringify is not a faithful representation of every JavaScript value — it is a format converter that silently normalizes or drops values that have no JSON equivalent. Code that relies on the output of JSON.stringify must verify its shape before use, especially for objects built from optional data sources.

Silent key drops are difficult to diagnose because the serialization succeeds — no error is thrown. The first sign is usually a client that receives a response missing an expected field and throws a TypeError like 'Cannot read property of undefined'. The client sees a field-absent response, but the server believes it sent the field because the server-side object had the key — it just had undefined as the value.

The fastest diagnostic is to console.log the object before serialization and then console.log the parsed serialized form side by side. Place this check in the request handler: const check = JSON.parse(JSON.stringify(responseBody)) and then compare Object.keys(responseBody) with Object.keys(check). Any key in the first set but not the second had an undefined value.

For TypeScript projects, a stricter type approach is to annotate API response objects with a type that includes null but excludes undefined. If you define type ApiUser = { phone: string | null } instead of { phone?: string }, the TypeScript compiler will flag any assignment of undefined to phone before the code reaches runtime. This moves the detection from the network layer back to the IDE.

In Express applications, you can add a middleware that intercepts outgoing JSON responses. By overriding res.json to compare the input object's key count with the serialized output's key count, you can emit a warning or throw when keys are dropped. This middleware approach catches the issue across all routes without modifying each handler individually. Combining it with structured logging allows you to record which routes are dropping which keys under which conditions.

The most direct fix is to normalize undefined values to null at the point where the response object is assembled. The nullish coalescing operator (??) is the cleanest tool for this: someValue ?? null returns someValue if it is neither undefined nor null, and returns null otherwise. Apply it to every field that might be undefined before the object reaches JSON.stringify.

For objects with many optional fields, a utility function is cleaner than individual ?? applications on each key. A function like const nullifyUndefined = (obj) => Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, v === undefined ? null : v])) applies the transformation to every top-level key in one pass. For deeply nested objects, extend it to recurse into nested structures or use a library like lodash's mapValues.

A replacer function passed to JSON.stringify can also handle this inline: (key, value) => value === undefined ? null : value. This converts every undefined value to null during serialization without modifying the original object. The advantage is that the original object in memory retains its undefined values, which may be semantically important for code that runs after serialization. The disadvantage is that you must remember to apply the replacer at every JSON.stringify call site.

For fetch calls, a common bug is using JSON.stringify without checking whether the result is undefined. A guard like const body = JSON.stringify(payload); if (body === undefined) throw new Error('Payload is not serializable'); catches the case where the entire payload is undefined, which JSON.stringify converts to the JavaScript undefined value rather than a string. Always verify the return value of JSON.stringify before using it as a request body.

TypeScript's type system distinguishes between optional fields and nullable fields, but both can lead to the same undefined-in-JSON problem at runtime. An optional field declared as phone?: string means the key may be absent from the object, and accessing it returns either a string or undefined. A nullable field declared as phone: string | null means the key is always present but may hold null as a value. JSON.stringify treats both situations differently: an absent key is never serialized, while a null value is serialized as the JSON null token.

When building API response types, the distinction matters enormously. If your OpenAPI spec says phone is nullable — meaning it is always present with either a string value or null — then the TypeScript type must be phone: string | null, not phone?: string. The optional syntax allows TypeScript code to assign undefined, which then gets silently dropped during serialization, violating the API contract.

The tsconfig option exactOptionalPropertyTypes, introduced in TypeScript 4.4, makes this stricter. When enabled, an optional field declared as phone?: string can receive a string but not explicitly undefined. Code like record.phone = undefined becomes a type error, which prevents the most common accidental undefined assignment. It does not prevent undefined from arriving via optional chaining or function return values, so it must be combined with runtime nullish coalescing rather than used as a complete solution.

The practical rule is: if a field appears in every response regardless of content, type it as field: ValueType | null and always assign either a real value or null. If a field is genuinely absent for certain objects — for example, a response type that has two variants — model it as a discriminated union or use separate response types rather than making every field optional. This approach makes the serialization contract visible in the type definitions and eliminates the ambiguity between missing and empty.

Express is the framework where this bug most commonly manifests because res.json is so convenient. A developer writes a route handler, assembles a response object from a database query, calls res.json, and ships the code. In testing with a complete database, every field is present and the response looks correct. In production with real data where some records have optional fields unset, the JSON response starts missing keys and clients begin throwing errors.

The issue is that Express calls JSON.stringify internally with no replacer, so any undefined field in the object passed to res.json is silently dropped. Express provides no warning, the HTTP response code is 200, and the content-length header reflects the actual shortened body. The only indication that something went wrong is the absence of a field that the API documentation says should always be present.

A common contributing factor is ORM result objects. Libraries like Prisma, Sequelize, and TypeORM return result objects where missing optional relations or columns may be undefined rather than null, depending on the query and the schema. When these result objects are passed directly to res.json without mapping to a response type, the undefined fields vanish. Always map ORM results to explicit response objects with controlled null handling rather than returning the ORM model instance directly.

Destructuring also introduces undefined silently. If you write const { name, phone, address } = userRecord and userRecord does not have a phone property, the destructured phone variable is undefined. Assigning it to the response object results in the same silent drop. Destructuring with defaults — const { phone = null } = userRecord — prevents this by substituting null for missing properties during destructuring, before the value reaches the response object.

The most effective long-term fix is establishing an explicit null policy in your API contract and enforcing it at the type and validation layers. The policy has two rules: first, a field that should always be present in a response must always be present, with null representing the absence of a value. Second, a field that is sometimes present and sometimes absent should be modeled as a discriminated union or as a separate response variant, not as an optional undefined field in a shared type.

Document this policy in your API reference. If phone can be absent, your docs should say phone: string or null — not phone: string, optional. This communicates to consumers that checking for null is the correct pattern, not checking for key existence. It also communicates to the backend team that every serialization path must ensure the field is explicitly assigned null when there is no value.

Validate outgoing responses at runtime using a schema validator. Tools like Zod, Ajv, or Joi can validate that the response object matches the declared schema before serialization. If a required field is undefined, the validator throws before JSON.stringify has a chance to silently drop it. Place this validation in a response serializer layer that all route handlers use, rather than in individual handlers.

For teams migrating an existing API, an incremental approach works well: add a response validation middleware that logs warnings for undefined fields without rejecting the response. This surfaces which endpoints and which fields are affected without breaking clients immediately. Once all warnings are addressed by converting undefined to null or restructuring the response type, upgrade the middleware to throw on undefined values. This two-phase approach lets you clean up a large codebase safely without a flag day.