Fix JSONDecodeError When Parsing JSON Files in Python

Python's json.load() can read a JSON file only when its contents follow JSON syntax exactly. You will learn how to interpret JSONDecodeError, correct invalid array entries, load the repaired file, and access nested dictionaries and lists.

JSON (JavaScript Object Notation) is a text format for structured data. Python translates JSON into built-in data types:

Think of JSON containers as two kinds of storage:

• An object ({}) is a labelled cabinet. Every item needs a label and a value: "id": "valore".
• An array ([]) is an ordered shopping basket. It holds values directly: "apple", 42, or an entire labelled cabinet such as { "id": "valore" }.

Putting "id": "valore" directly in an array is like trying to attach a cabinet label to the basket itself. Put the labelled item in a cabinet first, then place that cabinet in the basket.

Load JSON from a file with json.load(). Use json.loads() only when the JSON is already in a Python string.

import json
from pprint import pprint

with open("data.json", encoding="utf-8") as file:
    data = json.load(file)

pprint(data)

A corrected version of the file, where masks and parameters are arrays of objects, is:

{
  "maps": [
    {
      "id": "blabla",
      "iscategorical": "0"
    },
    {
      "id": "blabla",
      "iscategorical": "0"
    }
  ]
   
    
       
    
  
   
   
    
       
    
  

Consider this JSON fragment:

"masks": [
  {
    "id": "valore"
  }
]

And this Python code:

masks = data["masks"]
first_mask = masks[0]
mask_id = first_mask["id"]
print(mask_id)

Execution proceeds as follows:

1. data["masks"] retrieves the value associated with the masks key. Its value is a Python list.
2. masks[0] retrieves the first item in that list. The item is a Python dictionary: {"id": "valore"}.
3. first_mask["id"] retrieves the string stored under the id key.
4. print(mask_id) prints valore.

If the JSON had contained "masks": ["valore"], then data["masks"][0] would already be the string ; attempting would fail because strings do not have dictionary keys.

• Application configuration: Store feature settings, service URLs, and environment-independent options in JSON files.
• API responses: A web service may return an array of user objects, such as [{"id": 1, "name": "Ava"}].
• Data exports: Import JSON produced by another system and loop over records in arrays.
• Metadata files: Describe maps, layers, reports, or assets using nested objects and lists.
• Automation scripts: Read a JSON job definition, validate required fields, and process each configured item.

In real projects, developers usually combine parsing with validation and defensive error handling.

Use a context manager so the file closes automatically, and catch errors when input might be invalid:

import json
from pathlib import Path

path = Path("data.json")

try:
    with path.open(encoding="utf-8") as file:
        data = json.load(file)
except FileNotFoundError:
    print(f"Configuration file not found: {path}")
except json.JSONDecodeError as error:
    print(f"Invalid JSON at line {error.lineno}, column {error.colno}: {error.msg}")
else:
    for map_item in data.get("maps", []):
        map_id = map_item.get("id")
        if not map_id:
            continue
        print(map_id)

Common project patterns include:

• Validation at the boundary: Check JSON immediately after loading it, before the rest of the application uses it.
• Safe defaults: Use data.get("maps", []) when an optional list may be absent.

Placing a key-value pair directly in an array

Broken JSON:

"masks": ["id": "valore"]

A colon is valid for an object property, not for an array item. Fix it by using an object:

"masks": [{"id": "valore"}]

Using single quotes

Broken JSON:

{'id': 'valore'}

JSON requires double quotes around keys and string values:

{"id": "valore"}

Python dictionary syntax allows single quotes, but JSON syntax does not.

Leaving a trailing comma

Broken JSON:

import json

# Read JSON from a file
with open("data.json", encoding="utf-8") as file:
    data = json.load(file)

# Parse JSON from a Python string
item = json.loads('{"id": "valore"}')

# Access nested data
value = data["maps"][0]["id"]

# Read an optional key with a fallback
maps = data.get("maps", [])

• JSON objects use {} and contain "key": value pairs.
• JSON arrays use [] and contain comma-separated values.
• A key-value pair inside an array must be wrapped in {}.
• JSON requires double quotes for keys and strings.
• Do not use trailing commas.
• JSONDecodeError includes a line and column to help locate invalid syntax.
• JSON booleans are true and false; JSON null is null.

Why does Python say “Expecting ',' delimiter” for valid-looking JSON?

The message means the parser expected the current array or object item to end or be followed by a comma. In this case, it encountered a colon in an array because "id": "valore" was not wrapped in an object.

Can an array contain an object in JSON?

Yes. This is common:

[{"id": "one"}, {"id": "two"}]

Is {"id": "valore"} valid JSON?

Yes. It is a JSON object with one key, id, and one string value, valore.

Why are single quotes invalid in JSON but valid in Python dictionaries?

JSON is a language-independent format with strict rules requiring double quotes. Python has its own literal syntax, which permits either single or double quotes for strings.

How do I find the line that caused a JSONDecodeError?

Read error.lineno and error.colno, or inspect the line and nearby preceding syntax. A missing comma or bracket just before the reported location can cause the error.

• Python dictionaries — JSON objects become dictionaries after parsing.
• Python lists — JSON arrays become lists after parsing.
• Nested data structures — JSON often combines dictionaries and lists at several levels.
• Exception handling — Catch JSONDecodeError when files or API data may be malformed.
• File handling with with open — Safely opens and closes JSON files.
• Data validation — Confirms that parsed JSON has the keys and value types an application expects.
• JSON Schema — A formal way to define and validate an expected JSON structure.