Пустой ввод в JSON: что значит «The document is empty.» и как исправить
Обновлено
Ничего не дали — ничего и не вернут. Пустая строка не документ JSON, и парсеру нечего из неё достать: большинство так и говорит, а некоторые молча возвращают null, и ошибка всплывает на три функции позже.
Как выглядит пустой JSON
Текст пустой или состоит из одних пробелов, табов и переводов строки. Руками такой файл почти никто не пишет. Он приходит из ответа без тела (204 No Content, запрос HEAD, сдавшийся прокси), из файла, который читают, пока другой процесс его ещё пишет, из незаданной переменной окружения или ключа хранилища, куда ничего не записали.
JSON.parse(''); // SyntaxError: Unexpected end of JSON input
JSON.parse(' \n '); // то же: пробелы не значение
JSON.parse('null'); // null: самый короткий способ сказать "ничего" в JSONИсправление — заранее решить, что значит «ничего». Если тело может быть пустым, проверить это до разбора; если отправитель свой, пусть отдаёт явное значение, а не тишину:
{"items": []}Почему пустая строка не JSON (RFC 8259)
RFC 8259, раздел 2 описывает весь документ одной строкой: JSON-text = ws value ws. Пробелы по краям необязательны, значение — обязательно. А пробельных символов ровно четыре (пробел, таб, перевод строки, возврат каретки), поэтому "" и " \n " нарушают одно и то же правило: значения между ними нет.
Самые короткие валидные документы — из одного токена: 0, "", null, true, [], {}. Если «данных нет» — законный ответ, его говорит один из них. Пустое тело не говорит ничего, и парсер не отличит намеренную пустоту от оборванного соединения.
Ошибки пустого JSON в разных парсерах
Каждое сообщение ниже получено запуском парсера на пустой строке 8 ноября 2026 года; версия — в первом столбце. Исключение — Firefox: его текст взят из исходников парсера SpiderMonkey, а в браузере он выглядит так: JSON.parse: unexpected end of data at line 1 column 1 of the JSON data.
| Парсер | Сообщение | Примечание |
|---|---|---|
Chrome 156, Node 24–25 (V8): JSON.parse | Unexpected end of JSON input. Перевод: «неожиданный конец ввода JSON» | Тот же текст у документа, оборванного на середине |
Chrome 156: response.json() | Failed to execute 'json' on 'Response': Unexpected end of JSON input. Перевод: «не удалось выполнить json у Response: неожиданный конец ввода JSON» | fetch в Node пишет только вторую половину |
| Firefox (SpiderMonkey) | unexpected end of data. Перевод: «неожиданный конец данных» | По исходникам |
| Safari 27 (JavaScriptCore) | JSON Parse error: Unexpected EOF. Перевод: «ошибка разбора JSON: неожиданный конец файла» | Без позиции, как все сообщения Safari о JSON |
Python 3.9–3.14: json.loads | Expecting value: line 1 column 1 (char 0). Перевод: «ожидалось значение: строка 1, колонка 1 (символ 0)» | Для одних пробелов позиция сдвигается в их конец |
Go 1.25–1.27: json.Unmarshal | unexpected end of JSON input. Перевод: «неожиданный конец ввода JSON» | Тот же текст у оборванного документа |
Java, Jackson 2.15–2.23: readValue | No content to map due to end-of-input. Перевод: «нечего разбирать: ввод кончился» | readTree("") не бросает исключение, а возвращает 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.. Перевод: «во вводе нет ни одного токена JSON; ввод должен начинаться с допустимого токена» | Дальше — LineNumber: 0 | BytePositionInLine: 0. |
C#, Newtonsoft.Json 13: JToken.Parse | Error reading JToken from JsonReader. Path '', line 0, position 0.. Перевод: «ошибка чтения JToken из JsonReader» | JsonConvert.DeserializeObject("") вместо ошибки возвращает null |
PHP 8.3: json_decode | Syntax error. Перевод: «синтаксическая ошибка» | Код ошибки 4; без флага исключения результат — просто null |
| Rust, serde_json 1.0 | EOF while parsing a value at line 1 column 0. Перевод: «конец файла при разборе значения» | Тот же текст у оборванного документа |
| jq 1.7.1 | Ни ошибки, ни вывода | jq читает поток значений, а пустой поток — это ноль значений |
| MySQL 8.4: столбец JSON | Invalid JSON text: "The document is empty." at position 0. Перевод: «неверный текст JSON: документ пуст, позиция 0» | Полное сообщение кончается на in value for column … |
| Валидатор JSON Statham | Пустой ввод, строка 1, колонка 1 | Код empty_input, в том числе для одних пробелов |
Три вещи стоит запомнить. V8 и Go пишут одни и те же слова для пустого и для оборванного ввода, так что по сообщению не понять, какой это случай: стоит вывести в лог длину текста. readTree у Jackson и DeserializeObject у Newtonsoft не падают вовсе, и ошибка переезжает в первую строку, которая тронет результат. А PHP возвращает null и для пустой строки, и для валидного документа null: нужно проверять json_last_error() или передавать JSON_THROW_ON_ERROR.
Как обработать пустой JSON в JavaScript, Python, Go, Java, C# и PHP
Проверить пустоту до разбора и вернуть то, что код ждёт вместо «ничего», обычно null. Каждый фрагмент запущен ровно в таком виде; всё остальное по-прежнему уходит в парсер и падает громко, как и должно.
JavaScript: ответ fetch, у которого может не быть тела
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);
}Как не пускать пустые ответы в парсер
- Отдавать значение, а не тишину. Если ответить нечего, эндпоинт возвращает
200сnull,[]или{}— или204, который клиенты не разбирают. Но никогда не200с пустым телом. - Смотреть на статус раньше тела. У
204,304и ответа наHEADтела нет по определению. Разбирать стоит, только когда статус ожидаемый, аContent-Type—application/json. - Писать файлы атомарно. Сначала во временный файл, потом переименовать поверх старого. Иначе читатель, открывший файл посреди записи, увидит его пустым или оборванным.
- Задавать значение по умолчанию. Незаданная переменная окружения или ключ хранилища приходят пустой строкой или
null; до разбора их стоит заменить на"{}"или своё умолчание.
Проверить пустой ввод в валидаторе
Попробовать: открыть пример с пустым вводом в валидаторе. Пустое поле или поле из одних пробелов, табов и переводов строки получает empty_input в строке 1, колонке 1. Неразрывный пробел (U+00A0) для JSON не пробел, поэтому поле из одних таких символов получит неожиданный символ.
- Unexpected end of JSON input: то же сообщение V8 для JSON, который начался и не закончился.
- Expecting value: line 1 column 1 (char 0): так Python отвечает на пустой ввод — и на HTML вместо JSON.
- Метка BOM: файл, пустой на вид, может хранить три невидимых байта.
- Все ошибки JSON — у каждой своя страница.
Пустой JSON: частые вопросы
Пустая строка — это валидный JSON?
Нет. RFC 8259 требует ровно одно значение, а в пустой строке или строке из пробелов его нет. Самые короткие валидные документы — 0, "", null, [] и {}.
{} и [] — то же самое, что пустой ввод?
Нет. {} — пустой объект, [] — пустой массив: законченные валидные значения. Пустой ввод — это отсутствие значения вообще.
Почему response.json() падает на ответе 204?
У ответа 204 нет тела, а json() разбирает текст тела — пустую строку. Сначала проверить response.status или прочитать text() и разбирать, только если он не пустой.
Что значит «The document is empty.» в MySQL?
MySQL получил пустую строку там, где ждал значение JSON: INSERT в столбец JSON или CAST(… AS JSON) от ''. Нужно записать NULL или значение JSON вроде null или {}.