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 JSONThe 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.
| Parser | Message | Note |
|---|---|---|
Chrome 156, Node 24–25 (V8): JSON.parse | Unexpected end of JSON input | Same text for a document cut off in the middle |
Chrome 156: response.json() | Failed to execute 'json' on 'Response': Unexpected end of JSON input | Node’s fetch reports only the second half |
| Firefox (SpiderMonkey) | unexpected end of data | From source |
| Safari 27 (JavaScriptCore) | JSON Parse error: Unexpected EOF | No position, as with every Safari JSON message |
Python 3.9–3.14: json.loads | Expecting value: line 1 column 1 (char 0) | For whitespace only, the position moves to its end |
Go 1.25–1.27: json.Unmarshal | unexpected end of JSON input | Same text for a cut-off document |
Java, Jackson 2.15–2.23: readValue | No content to map due to end-of-input | readTree("") throws nothing and returns a MissingNode |
| C#, System.Text.Json 10 | The 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.Parse | Error reading JToken from JsonReader. Path '', line 0, position 0. | JsonConvert.DeserializeObject("") returns null instead |
PHP 8.3: json_decode | Syntax error | Error code 4; without the throw flag the result is plain null |
| Rust, serde_json 1.0 | EOF while parsing a value at line 1 column 0 | Same text for a cut-off document |
| jq 1.7.1 | No error and no output | jq reads a stream of values, and an empty stream is zero values |
| MySQL 8.4: JSON column | Invalid JSON text: "The document is empty." at position 0 | The full message ends with in value for column … |
| JSON Statham Validator | Empty input, line 1, column 1 | Code 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
200withnull,[]or{}, or204that clients know not to parse. Never200with an empty body. - Look at the status before the body.
204,304and answers toHEADhave no body by definition. Parse only when the status is the one you expect andContent-Typeisapplication/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.
- Unexpected end of JSON input: the same V8 message for JSON that starts and never finishes.
- Expecting value: line 1 column 1 (char 0): Python’s message for empty input, and for an HTML page where JSON was expected.
- Byte order mark: a file that looks empty in an editor may still hold three invisible bytes.
- All JSON errors, each with its own page.
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 {}.