Technology · PRACTICAL GUIDE
JSONDecodeError at line 1 column 1? Inspect the bytes before fixing the parser
Character zero says where decoding failed, not why. Preserve the status, media type, body length and a safe byte fingerprint; classify empty, HTML, decoding or truncated input; repair the producer or caller contract; then verify valid, empty and invalid fixtures.
Character zero says where decoding failed, not why. Preserve the status, media type, body length and a safe byte fingerprint; classify empty, HTML, decoding or truncated input; repair the producer or caller contract; then verify valid, empty and invalid fixtures.
A JSON text contains one serialized value; an empty or whitespace-only body is not JSON. Python raises JSONDecodeError when the supplied document is not valid JSON.
1. Freeze the envelope before parsing
Record method, redacted URL, status, redirects, Content-Type, Content-Encoding, declared length, received byte count, runtime and exact exception. Capture a body hash and only a short redacted prefix when policy permits; never log tokens, cookies or a full personal payload.
Read the body once and preserve whether it was absent, zero bytes, whitespace, HTML, JSON-like text or undecodable bytes. Do not call json(), text() and json() again on the same consumed stream and mistake that second failure for the producer fault.
2. Classify what begins at character zero
Empty or whitespace at position zero points to a no-body contract, premature close or discarded payload. A leading less-than sign often means HTML from a login, proxy or error page. Other first bytes can reveal a wrong endpoint, BOM, encoding mismatch or compression problem.
Separate syntax after real JSON begins from character-zero failures. Record the parser line, column and absolute position, but treat them as locations. Validate the whole document because trailing data, truncation and concatenated JSON values require different repairs.
3. Trace the producer and transformation path
Follow the response from application handler through middleware, proxy, cache, decompressor and client library. Match request ID and timestamps without copying secrets. Confirm which layer set the status, media type, encoding and body and whether a redirect changed the endpoint.
For files, prove the exact path, byte length, encoding and atomic-write boundary. A new empty file, stale temp file or concurrent partial write is not fixed by relaxing the JSON parser. Preserve the failing bytes before another writer replaces them.
4. Repair the contract, not the symptom
If a success intentionally has no representation, model that branch explicitly and do not parse it. If JSON is promised, make the producer return a valid JSON value and correct Content-Type; fix authentication, proxy or routing when HTML arrived; repair encoding or decompression at the responsible layer.
Catch the narrow decoder exception only to add safe context or convert it into a typed contract error. Do not return an empty object, retry every syntax error or strip arbitrary characters: those actions can hide data loss, duplicate side effects or an upstream outage.
5. Verify three fixtures and observable failure
Test a valid JSON response, an intentional no-body response and an invalid or wrong-media response. The valid fixture must parse to the expected type, the empty fixture must take the documented no-content branch, and the invalid fixture must fail with the typed diagnostic and safe evidence.
Under representative traffic, verify parse-error rate, body-length distribution, status and media-type mismatches, redirects and retries. Success means the producer and consumer agree, failures stay visible, sensitive bodies are not logged, and rollback is defined.
