How to diagnose JSON errors step by step

JSON looks simple because it has few data types and familiar punctuation. That is exactly why a small mistake often reaches a tool as an unhelpful message: an unexpected comma, a position, or “invalid token”. The goal is not to guess until the document stops failing. Reduce the case, locate the reported position, make a grammar-compatible correction, and verify that the data still means the same thing.

RFC 8259 defines JSON as a data interchange format built from objects, arrays, numbers, strings, booleans, and null. Object names are strings enclosed in double quotes. A string cannot contain a literal line break. Commas separate values; they do not finish a list with an extra separator. Those strict rules are intentional: different programs need to reach the same interpretation.

A parser checks syntax, not intent. It can say where it stopped understanding the document, but it cannot know whether two differently named fields represent the same price, whether an identifier lost its leading zeroes, or whether a date uses the right time zone. Separate the error that prevents JSON from being read from a semantic issue that remains after formatting.

A complete reproducible example

Start with a small copy that contains no real secrets. This payload combines four common problems. The order matters because a parser normally reports the first obstacle and hides the rest until that one is repaired.

{
  "customer": "Ada",
  "items": ["notebook", "pen",],
  "note": "Deliver before
Friday",
  'orderId': "007",
  "total": 24.90,
  "amount": 24.90
}

The comma after "pen" is trailing. The break between before and Friday occurs inside an unescaped string. orderId uses single quotes, which JavaScript accepts in some contexts but JSON does not. Finally, total and amount are syntactically valid. A parser accepts them even though they may describe the same amount. That last question needs somebody who knows the API contract.

Reading a parser position

JSON.parse() errors often mention a position, a line, or a column, depending on the engine and browser. Count from the beginning of the exact input supplied to the parser, including whitespace and line breaks. Do not assume the position is the root cause. It frequently marks the character where grammar can no longer continue. A trailing comma may be reported at ]; an unescaped string may be reported at the line break.

Use an editor that shows line and column numbers. Copy text without changing quotation marks, and avoid a messaging application that inserts spaces or line breaks. When a tool shows an absolute position, inspect twenty characters on either side. When it shows a line, inspect the preceding line too: a delimiter often opens before the symptom appears.

The practical problem is telling an unreadable payload apart from a payload that is valid but wrong for the business. A formatter can only work after grammar is valid. When the document came from a log, an environment variable, or an HTTP response, keep the original copy first and record which system produced it. Do not replace values blindly: a change that removes an error can alter a signature, a checksum, or an identifier. Reduce the sample to the block that reproduces the failure and remove personal data before sharing it.

Diagnose the example in four passes. First, go to the items line; the comma immediately before ] does not separate another value and must be removed. Second, locate the reported line inside note; JSON represents the line break as a backslash followed by n, not as a physical break. Third, replace the single quotes around the key with double quotes. Fourth, ask the data producer whether total and amount are distinct concepts. If they are the same amount, keep the established name and document the migration.

{
  "customer": "Ada",
  "items": ["notebook", "pen"],
  "note": "Deliver before\nFriday",
  "orderId": "007",
  "total": 24.90
}

The corrected JSON parses, preserves orderId as a string so its zeroes remain, and encodes the line break portably. Do not change "007" into a number merely because it looks numeric. Codes and references have rules that differ from quantities.

Begin by running the parser in the environment that failed, when possible. Note the message and position before rewriting any text. Validate a copy in a formatter; if the message changes, check whether the input was normalized. Fix one syntax error, parse again, and repeat. When the result is valid, compare meaningful keys, types, lengths, and values with a known sample. For an API, compare the document with its schema or contract as well. A schema can require fields and formats, but it cannot independently decide which amount is correct.

In automation, capture the error text and nearby context, not an entire sensitive payload. In JavaScript, place JSON.parse() inside exception handling and return a diagnosis that does not expose tokens. In an integration, retain the request identifier, contract version, and an anonymized sample. That practice makes the problem reproducible without turning debug logs into another disclosure.

Double quotes, backslashes, and commas are syntax rather than optional style. Inside a string, \n represents a line break, \" represents a quote, and \\ represents a backslash. An open string can make the parser blame a later character. Likewise, a missing brace or bracket may be reported at the end of the document, because only then is the missing closure certain.

Exact duplicate names are especially risky: many parsers keep the last occurrence, while RFC 8259 warns that behavior for non-unique names is unpredictable across implementations. Semantic duplicates such as total and amount are harder: both can survive and produce two interpretations. Define a canonical name, reject the ambiguous combination at the producer, and add a test that covers the transition.

Avoid “repair” tools that turn arbitrary JavaScript-like text into JSON without reporting their changes. Adding quotes, deleting commas, or converting values can hide a producer incompatibility. Do not use regular expressions to validate complete JSON either; escaped strings and nesting make that approach brittle. The parser is the authority for syntax; contract tests and schema validation cover requirements after parsing.

Another common failure is treating valid JSON as a correct response. {"enabled":"false"} is valid, but the type might need to be boolean. 9007199254740993 can lose precision when it becomes a JavaScript number. A date such as 03/04/2026 does not explain its order. Check type, unit, time zone, range, and business rules before handing a value to another layer.

Use synthetic data to learn the workflow and confirm where a tool processes content before pasting internal information. For a large payload, split the investigation: validate the header, one array item, and the closing structure. Do not cut in the middle of a string or UTF-8 sequence. Preserve UTF-8 encoding and avoid word processors that replace straight quotation marks with typographic ones.

Error messages vary between browsers and releases. A position number is reproducible only for the exact same input. Include client version, literal message, sanitized fragment, and reproduction steps in a report. Never publish a complete payload as an “example” when it includes email addresses, internal paths, sessions, or account numbers.

This guide does not certify that a payload is safe, authorized, or suitable for a professional decision. JSON does not encrypt, sign, or validate permissions. A well-formed document can contain a malicious instruction, stale data, or manipulated figures. Syntax validation does not replace authentication, authorization, size limits, safe logging, or human review where context requires it.

Browser tools can help inspect text, but they should not be the only control for a critical integration. For payments, health, security, legal duties, or regulated data, follow the contract, procedures, and approved environments of the responsible organization. If you do not know what a duplicate field means, stop the import and ask the data owner.

Before calling a JSON error solved, keep a protected copy of the input and create a minimal example without secrets. Read the first parser message and locate its position in the exact input. Repair one syntax rule at a time: commas, quotes, escapes, and closures. Parse again after each change. Once it passes, compare keys, types, identifiers, numbers, dates, and equivalent fields with the contract. Confirm there are no duplicate names or overlapping meanings. Finally, test the real consumer with controlled data, record the root cause, and fix the producer so it cannot emit the same document again.