5 ways to debug JSON parsing failures faster (without guessing)

JSON has become the de facto universal data format, used for everything from local configuration to remote API responses. But the more you depend on JSON, the more you have to deal with related issues that can arise.

The JSON syntax is small and simple, but it’s easy for buggy code or overworked humans to generate invalid JSON. In fact, because the format is stricter than its equivalent notation in JavaScript, errors are almost inevitable. The key is to recognize them and know how to deal with them.

Use a syntax highlighting editor

Prevention is better than cure, and one way to resolve JSON syntax issues is to avoid them in the first place. Modern text editors and IDEs offer excellent syntax highlighting, auto-completion, and auto-formatting features, which can help you spot errors immediately.

My editor of choice is Zed, and one thing I like about it is the excellent Language Server Protocol (LSP) support. This helps provide features like autocomplete and reformatting, which can be incredibly useful when writing JSON:

The editor’s auto-format feature when saving can even clean up some errors for you; for example, this will fix this malformed JSON:

{
    hello: "world"
}

When saving, Zed will automatically add quotes to the key, ensuring the JSON is valid:

{
    "hello": "world"
}

The editor will only correct your JSON when it can do so unambiguously, so it won’t be able to catch every error, but it will always flag errors and highlight the offending section.

Most IDEs and editors offer similar functionality, but I like Zed for its speed and it’s a nice lightweight alternative to VS Code.

Use an online validator

There are many JSON validators, formatters, and editors online; a quick search will uncover more than you might need. JSONLint is one of the best, and it’s my first choice when debugging JSON, for two reasons.

First, just like Zed, the browser’s text box responds in real time, so you can spot errors as you type (or paste) your JSON. This is a step up from many online forms-based validators that only verify your JSON on demand, with the press of a button.

Second, JSONLint has slightly nicer error messages than many of its competitors. Compare its error “Property keys must be in quotes” with “Expected ‘STRING’, ‘}’, got ‘undefined’ from JSON Checker, for example. Many validators simply pass the underlying error message from the browser’s JavaScript engine, which can be low-level and particularly confusing to non-programmers. JSONLint, on the other hand, reinterprets each error with a friendlier and more descriptive message.

JSONLint has many related features, such as an option to repair invalid JSON and support for validation against a JSON schema. With a total of 42 focused tools, the site will allow you to do almost anything you can think of with JSON.

Use a command line linter

If you prefer to work from the command line, don’t worry; you are not left out here! The JSON Lint program does pretty much the same thing as the website of the same name, only in your terminal.

Note that this does not have the same error messages as the web application and is basically a non-interactive tool. I would only suggest this option if you regularly need to work offline or in a GUI-less environment: when connecting via SSH to a remote machine, for example.

Use a JSON processor from the command line

Another command line program is much more established in the JSON world: jq. This utility is more about processing JSON than just validating it, but it is very widely available and much more useful beyond debugging errors.

jq works on JSON in the input stream, so you can redirect the JSON there or redirect it from a file:

jq 

Again, this tool won’t give you the most user-friendly error messages, but it clearly shows the row and column numbers.

The only other feature worth noting is that of jq --stream-errors option. This flag makes the jq output a more structured representation of each error, with potentially more detail, so it can be useful when creating scripts or used with an AI agent.

Use a terminal JSON viewer

There is another type of JSON tool that can notify you of errors while performing another task: JSON viewers. I regularly use two of them (fx and jless) but, as with many of these options, they differ greatly in the error messages they produce:

In this case, the fx error is much easier to understand than the jless error.

The only drawback of these tools (and of jslint and jq) is that they do not detect all errors. For example, a JSON object with duplicate property names can cause many problems, but these tools will silently ignore them.

Use JSON.parse in your browser console

Finally, if you’re firmly in the zone and don’t want to leave your browser’s JavaScript environment at all, a quick JSON.parse() can help you get to the bottom of a problem:

This is really the lowest level option, and you’ll have to deal with more obscure error messages and detailed stack traces, but it can definitely help in a pinch.