Complete guide to JSON errors

A JSON error can come from syntax, character encoding, an incomplete response, or data that is valid but violates the contract. Classifying the failure first is faster than trying random punctuation changes.

1. Preserve the failing input

Work with the exact bytes that failed. A formatted console preview may hide control characters, truncate a long response, or display an HTML error page as if it were ordinary text. For HTTP failures, capture the status code, Content-Type, response length, and a safely redacted excerpt before calling the parser. Do not log tokens, credentials, or complete customer payloads.

2. Separate syntax from transport problems

JSON syntax uses double-quoted strings, commas between values, and balanced braces or brackets. Comments, trailing commas, single-quoted strings, NaN, and undefined are not valid JSON. Use the JSON Validator to obtain a line and column, then inspect the character immediately before and after that location.

An error near the first character often means the body is not JSON at all. Common examples are a proxy-generated HTML page, a plain-text authentication error, or an empty 204 No Content response. An error at the end often points to a missing closing token or a truncated download. Confirm the complete body arrived before editing it.

3. Read common parser messages correctly

Unexpected token means the parser found a character that cannot appear at that position. Check for unquoted keys, single quotes, comments, and HTML. Unexpected end of JSON input means the parser still expected a value, quote, bracket, or brace when the text stopped. A bad control character usually means a literal tab or newline exists inside a quoted string instead of an escaped sequence such as \n.

Parser wording differs between JavaScript engines and languages, but the underlying grammar failure is usually the same. Reduce a large payload to the smallest failing object while preserving the original privately for comparison.

4. Check encoding and invisible characters

JSON exchanged on the web should normally be UTF-8. A byte-order mark, invalid byte sequence, non-breaking space, or copied smart quote can produce confusing locations. Inspect the raw file in an editor that can reveal whitespace and encoding. Normalize at the system boundary only when the source format is known; replacing arbitrary bytes can corrupt real data.

5. Validate the shape after parsing

A successful parse only proves that the text follows JSON grammar. It does not prove that user.id exists, that price is a number, or that an enum value is supported. Apply JSON Schema or explicit application validation after parsing. Keep syntax errors and contract errors distinct so users receive an actionable message instead of a generic “invalid JSON.”

6. Repair only when the intent is knowable

JSON Repair can help with human-authored text containing trailing commas, missing quotes, or obvious closing delimiters. It cannot reconstruct the missing half of a network response or infer a business-critical value. Show the proposed change, let the user review it, and validate the repaired result. Server-to-server integrations should normally reject malformed input and fix the producer.

A repeatable debugging checklist

1. Capture the exact input and surrounding response metadata.
2. Confirm the body is complete and actually intended to be JSON.
3. Validate syntax and inspect the reported line and column.
4. Check encoding, invisible characters, and file boundaries.
5. Validate the parsed value against the expected schema.
6. Add the smallest failing example to an automated regression test.

Frequently Asked Questions

Related Tools and Guides