JSON (JavaScript Object Notation) has strict syntax requirements, and any violation causes the entire document to be rejected as invalid. Unlike HTML which browsers attempt to render even with errors, a JSON parser that encounters a syntax error stops and returns an error, giving you no partial result to work with. Finding the exact character causing the error in a large JSON document can be frustrating without knowing what to look for.
The most common JSON syntax errors
Trailing commas are the most frequent error for developers coming from JavaScript, Python, or other languages that permit trailing commas in arrays and objects. JSON does not allow a comma after the last item in an array or the last property in an object. The error "Unexpected token }" or "Expected string" in a JSON parser usually points to a trailing comma immediately before the closing bracket.
Unquoted keys are another JavaScript-influenced error. In JavaScript object literals, keys can be unquoted. In JSON, all keys must be quoted with double quotes. A JavaScript object like {name: "Ahmad"} is not valid JSON. The valid JSON equivalent is {"name": "Ahmad"}.
Single quotes instead of double quotes is a Python-influenced error. JSON specifies double quotes for all strings and keys. Single quotes are not valid JSON even though they work in JavaScript and Python string literals. {"name": 'Ahmad'} is invalid JSON. {"name": "Ahmad"} is valid.
Mismatched brackets and braces cause cascade errors where the parser reaches the end of the document without all opened structures being closed. A missing closing bracket ] for an array or closing brace } for an object causes an "Unexpected end of JSON input" error. A count of open and close brackets in the document should match.
Undefined and NaN values are JavaScript-specific values that are not valid in JSON. JSON has null for absence of value. A field with undefined as its value is invalid JSON. A field with NaN (Not a Number) is also invalid. Replace undefined with null and NaN with null or a valid numeric string.
Comments are not permitted in JSON. Standard JSON does not have a comment syntax. JSON files containing C-style or hash comments are invalid. If you need annotated configuration files, consider JSON5 (a superset of JSON that allows comments) or YAML instead of standard JSON.
Encoding and character issues
JSON must be valid Unicode, typically UTF-8. Files encoded in Windows-1252 or Latin-1 that contain non-ASCII characters like accented letters may appear valid when viewed in a text editor but fail JSON parsing because the byte sequences for those characters are not valid UTF-8.
Unescaped control characters within strings cause parsing failures. A newline character embedded directly in a JSON string value is invalid. Newlines within string values must be represented as the escape sequence . Tab characters must be . This is a common error when constructing JSON by concatenating strings that may contain user-entered text with literal newlines.
BOM (Byte Order Mark) at the start of a UTF-8 file causes some JSON parsers to fail. The BOM is a zero-width character that some text editors add to the beginning of UTF-8 files. It is not visible but causes a syntax error because the parser sees an unexpected character before the opening bracket of the JSON.
Diagnosing a JSON error efficiently
Most JSON parsers report the line number and character position of the error. Start at the reported position and look for the common errors listed above. The actual error is often a character or two before the reported position because the parser detects the problem when it encounters the unexpected character, which may follow the actual source of the error.
Use a JSON formatter and validator to structure the JSON and highlight the error position visually. The JSON Formatter tool validates JSON as you type and highlights any syntax errors, making it easy to find problems in large documents.
For large JSON files where the error is not immediately obvious, binary search is an efficient approach: take the first half of the document, check if it is valid JSON (it will not be if the issue is unmatched brackets, but will be if the issue is a specific invalid value). Narrow down the section containing the error by repeatedly halving the search space.
Preventing JSON errors in generated output
If you are generating JSON programmatically, always use a JSON serialisation library rather than constructing the string by hand. Every major programming language has a built-in or standard library JSON encoder that handles all escaping, quoting, and formatting correctly. Hand-constructed JSON strings are the most common source of JSON errors in production systems.
Validate generated JSON in your test suite. A test that serialises your data structures to JSON and then parses the result catches serialisation errors before they reach production. This is particularly important when the data includes user-entered text that may contain special characters.