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

> Fix empty JSON input: what each parser says about an empty string, whitespace or a 204 response, and how to check for it before parsing.

- URL: https://jsonstatham.dev/errors/empty-input/
- Language: English (en)
- Russian version: https://jsonstatham.dev/ru/errors/empty-input.md
- Updated: 2026-11-08

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.

```js
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:

```json
{"items": []}
```

## Why an empty string is not JSON (RFC 8259)

[RFC 8259, section 2](https://www.rfc-editor.org/rfc/rfc8259#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](https://jsonstatham.dev/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

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

### Python

```python
import json

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

### Go

```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)

```java
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)

```csharp
using System.Text.Json.Nodes;

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

### PHP

```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](https://jsonstatham.dev/errors/unexpected-end-of-json-input/).
- **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](https://jsonstatham.dev/validator/?sample=empty_input). 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](https://jsonstatham.dev/errors/unexpected-character/) instead.

- [Unexpected end of JSON input](https://jsonstatham.dev/errors/unexpected-end-of-json-input/): the same V8 message for JSON that starts and never finishes.
- [Expecting value: line 1 column 1 (char 0)](https://jsonstatham.dev/errors/expecting-value/): Python’s message for empty input, and for an HTML page where JSON was expected.
- [Byte order mark](https://jsonstatham.dev/errors/bom/): a file that looks empty in an editor may still hold three invisible bytes.
- [All JSON errors](https://jsonstatham.dev/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 `{}`.
