JSON.parse() fails on text it cannot read. What exactly does it do on malformed input, what kinds of real-world input trigger it, and how should production code handle those failures?

## What actually happens `JSON.parse(text)` either returns a fully-built value or throws. There is no partial result, no `null` return, no error flag: if the text does not match the JSON grammar from the first character to the last, the call throws a **`SyntaxError`** — the same built-in error type the engine uses for source it cannot parse. The throw is synchronous, on the same call stack, so the handling is an ordinary `try`/`catch`: ```js let value; try { value = JSON.parse(text); } catch (err) { // err instanceof SyntaxError } ``` A detail that catches people out: the argument is coerced to a string before parsing. So `JSON.parse(null)` becomes the text `"null"` and returns `null` with no complaint, while `JSON.parse(undefined)` becomes the text `"undefined"`, which is not valid JSON, and throws. An accidental `undefined` reaching the parser surfaces as a syntax error rather than as the missing-value error you would expect. ## The grammar is stricter than people remember JSON is not JavaScript object literal syntax. All of the following throw: ```js JSON.parse("{'a': 1}"); // single-quoted string JSON.parse('{a: 1}'); // unquoted key JSON.parse('{"a": 1,}'); // trailing comma JSON.parse('{"a": 1} // x');// comment JSON.parse('{"a": NaN}'); // NaN is not a JSON literal JSON.parse(''); // empty text is not a JSON value JSON.parse('{"a":1}');// leading byte-order mark ``` The byte-order-mark case is worth memorising because it is invisible in a terminal and in most editors. Only space, tab, carriage return and line feed count as whitespace in JSON; U+FEFF does not, so a file saved as "UTF-8 with BOM" fails to parse while looking perfectly correct on screen. ## What actually breaks in production In real incidents the input is usually not slightly-wrong JSON — it is not JSON at all: - **An HTML error page.** A gateway, load balancer, captive portal or authentication redirect returns a styled 502 or login page. The text starts with `<`, and the parse fails at position 0. This is far and away the most common cause. - **An empty body.** A 204 response, a closed connection, or a handler that returned nothing. - **A truncated payload.** The connection dropped mid-stream, a size limit clipped the body, or a log line was cut. The text is valid JSON right up to the point where it stops. - **A plain-text error.** A proxy writing `upstream timed out` or a health-check probe answering `OK`. - **A wrong encoding or a stray BOM** on a file read from disk. The pattern in all of these is the same: something upstream substituted a different content type for the one you expected, and the parser is simply where you find out. ## Handling it well **Parse at a boundary.** Do the parsing at the edge where you know what the text was supposed to be and who produced it, and hand the rest of the system a value. A `SyntaxError` escaping from deep inside business logic tells nobody anything. **Catch narrowly and rethrow the rest.** Inside the `catch`, confirm you are handling a parse failure rather than swallowing an unrelated bug: ```js try { return JSON.parse(text); } catch (err) { if (!(err instanceof SyntaxError)) throw err; // handle the parse failure } ``` **Log evidence, bounded.** The `SyntaxError` message tells you what the parser choked on; what you actually need is what arrived. Record the text's length and a short prefix — the first 80 or so characters — plus the source and, where you have it, the declared content type. A prefix of `<!DOCTYPE html>` diagnoses the incident instantly. Keep the prefix bounded so a large body cannot flood the log, and be deliberate about payloads that may contain sensitive fields. **Never branch on the message text.** The wording, and whether it mentions a position or an offending token, is engine-specific and changes between versions. Use the error *type* for control flow and treat the message as human-readable evidence only. **Do not confuse a transport failure with a parse failure.** "Could not reach the service" and "the service answered with something that is not JSON" have different causes, different owners and different retry semantics. Keep them as separate outcomes rather than collapsing both into one generic error. **Decide what happens next, explicitly.** A helper that returns a discriminated result — success with a value, or failure with diagnostics — forces every caller to make that decision instead of silently receiving `null`. Returning a default on failure is a legitimate choice for a cache read and a bad one for a payment callback; the point is that it be a choice. ## One thing parsing does not give you Success means only that the text was well-formed. It says nothing about whether the value has the fields you need, or the right types in them. Structural checking of the parsed value is a separate step, and code that treats a successful parse as confirmation of shape simply moves the failure a little further downstream.