ENRU

Empty input in JSON: what “The document is empty.” means and how to fix it

Updated

Nothing in, nothing out. An empty string is not a JSON document, and a parser handed one has nothing to return: most say so, a few quietly return null and let the bug surface three functions later.

What empty JSON input looks like

The text is empty or holds only whitespace: spaces, tabs, line breaks. It rarely starts in a file you typed. It comes from a response with no body (204 No Content, a HEAD request, a proxy that gave up), a file read while another process was still writing it, an environment variable that was never set, or a storage key nobody wrote.

JSON.parse('');      // SyntaxError: Unexpected end of JSON input
JSON.parse(' \n ');  // the same: whitespace is not a value
JSON.parse('null');  // null: the shortest way to say "nothing" in JSON

The fix is to decide what “nothing” means before the parser sees it. If the body may be empty, check for that; if you control the producer, send an explicit value instead of silence:

{"items": []}

Why an empty string is not JSON (RFC 8259)

RFC 8259, section 2 defines the whole document in one line: JSON-text = ws value ws. Whitespace is optional on both sides; the value is not. And whitespace is exactly four characters (space, tab, line feed, carriage return), so "" and " \n " break the same rule: there is no value between them.

The smallest valid documents are one token long: 0, "", null, true, [], {}. If “no data” is a legitimate answer, one of them says it. An empty body says nothing, and the parser can’t tell an intentional nothing from a broken connection.

Empty input error messages by parser

Each message below was produced by running the parser on an empty string on 2026-11-08; the version is in the first column. Firefox is the exception: its text is taken from the SpiderMonkey parser source, and Firefox prints it as JSON.parse: unexpected end of data at line 1 column 1 of the JSON data.

ParserMessageNote
Chrome 156, Node 24–25 (V8): JSON.parseUnexpected end of JSON inputSame text for a document cut off in the middle
Chrome 156: response.json()Failed to execute 'json' on 'Response': Unexpected end of JSON inputNode’s fetch reports only the second half
Firefox (SpiderMonkey)unexpected end of dataFrom source
Safari 27 (JavaScriptCore)JSON Parse error: Unexpected EOFNo position, as with every Safari JSON message
Python 3.9–3.14: json.loadsExpecting value: line 1 column 1 (char 0)For whitespace only, the position moves to its end
Go 1.25–1.27: json.Unmarshalunexpected end of JSON inputSame text for a cut-off document
Java, Jackson 2.15–2.23: readValueNo content to map due to end-of-inputreadTree("") throws nothing and returns a MissingNode
C#, System.Text.Json 10The input does not contain any JSON tokens. Expected the input to start with a valid JSON token, when isFinalBlock is true.Followed by LineNumber: 0 | BytePositionInLine: 0.
C#, Newtonsoft.Json 13: JToken.ParseError reading JToken from JsonReader. Path '', line 0, position 0.JsonConvert.DeserializeObject("") returns null instead
PHP 8.3: json_decodeSyntax errorError code 4; without the throw flag the result is plain null
Rust, serde_json 1.0EOF while parsing a value at line 1 column 0Same text for a cut-off document
jq 1.7.1No error and no outputjq reads a stream of values, and an empty stream is zero values
MySQL 8.4: JSON columnInvalid JSON text: "The document is empty." at position 0The full message ends with in value for column …
JSON Statham ValidatorEmpty input, line 1, column 1Code empty_input, also for whitespace only

Three of these are worth remembering. V8 and Go use the same words for empty and truncated input, so the message alone doesn’t tell you which one you have: log the length of the text. Jackson’s readTree and Newtonsoft’s DeserializeObject don’t fail at all, which moves the error to the first line that touches the result. And PHP returns null for both an empty string and the valid document null, so check json_last_error() or pass JSON_THROW_ON_ERROR.

How to handle empty JSON in JavaScript, Python, Go, Java, C# and PHP

Check for emptiness before parsing and return what your code expects for “nothing”, usually null. Every snippet below was run as shown; anything else still goes to the parser and fails loudly, as it should.

JavaScript: a fetch response that may have no body

async function readJson(response) {
  const text = await response.text();
  if (text.trim() === '') return null;
  return JSON.parse(text);
}

Python

import json


def load_or_none(text):
    if not text.strip():
        return None
    return json.loads(text)

Go

import (
	"bytes"
	"encoding/json"
)

func parseOrNil(data []byte) (any, error) {
	if len(bytes.TrimSpace(data)) == 0 {
		return nil, nil
	}
	var v any
	err := json.Unmarshal(data, &v)
	return v, err
}

Java (Jackson)

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

static JsonNode parseOrNull(ObjectMapper mapper, String text) throws JsonProcessingException {
    if (text == null || text.isBlank()) {
        return null;
    }
    return mapper.readTree(text);
}

C# (System.Text.Json)

using System.Text.Json.Nodes;

static JsonNode? ParseOrNull(string? text) =>
    string.IsNullOrWhiteSpace(text) ? null : JsonNode.Parse(text);

PHP

function parse_or_null(string $text): mixed
{
    if (trim($text) === '') {
        return null;
    }
    return json_decode($text, true, 512, JSON_THROW_ON_ERROR);
}

How to keep empty responses out of your parser

  • Send a value, not silence. An endpoint with nothing to report answers 200 with null, [] or {}, or 204 that clients know not to parse. Never 200 with an empty body.
  • Look at the status before the body. 204, 304 and answers to HEAD have no body by definition. Parse only when the status is the one you expect and Content-Type is application/json.
  • Write files atomically. Write to a temporary file and rename it over the old one. A reader that opens a file mid-write sees it empty or cut off halfway.
  • Default what may be unset. Environment variables and storage keys that were never written come back as an empty string or null; turn that into "{}" or your default before parsing.

Check empty input in the validator

Try it: open the empty-input sample in the Validator. An empty field, or one holding only spaces, tabs and line breaks, gets empty_input at line 1, column 1. A no-break space (U+00A0) is not JSON whitespace, so a field holding only that gets Unexpected character instead.

Empty JSON input FAQ

Is an empty string valid JSON?

No. RFC 8259 requires exactly one value, and an empty string, or one made of whitespace, has none. The shortest valid documents are 0, "", null, [] and {}.

Are {} and [] the same as empty input?

No. {} is an empty object and [] an empty array: complete, valid JSON values. Empty input is the absence of any value at all.

Why does response.json() fail on a 204 response?

A 204 has no body, and json() parses the body text, which is an empty string. Check response.status first, or read text() and parse only when it isn’t empty.

What does “The document is empty.” mean in MySQL?

MySQL got an empty string where a JSON value was expected: an INSERT into a JSON column or a CAST(… AS JSON) of ''. Store NULL instead, or a JSON value such as null or {}.