ENRU

Пустой ввод в 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.parseUnexpected 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.loadsExpecting value: line 1 column 1 (char 0). Перевод: «ожидалось значение: строка 1, колонка 1 (символ 0)»Для одних пробелов позиция сдвигается в их конец
Go 1.25–1.27: json.Unmarshalunexpected end of JSON input. Перевод: «неожиданный конец ввода JSON»Тот же текст у оборванного документа
Java, Jackson 2.15–2.23: readValueNo content to map due to end-of-input. Перевод: «нечего разбирать: ввод кончился»readTree("") не бросает исключение, а возвращает 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.. Перевод: «во вводе нет ни одного токена JSON; ввод должен начинаться с допустимого токена»Дальше — LineNumber: 0 | BytePositionInLine: 0.
C#, Newtonsoft.Json 13: JToken.ParseError reading JToken from JsonReader. Path '', line 0, position 0.. Перевод: «ошибка чтения JToken из JsonReader»JsonConvert.DeserializeObject("") вместо ошибки возвращает null
PHP 8.3: json_decodeSyntax error. Перевод: «синтаксическая ошибка»Код ошибки 4; без флага исключения результат — просто null
Rust, serde_json 1.0EOF while parsing a value at line 1 column 0. Перевод: «конец файла при разборе значения»Тот же текст у оборванного документа
jq 1.7.1Ни ошибки, ни выводаjq читает поток значений, а пустой поток — это ноль значений
MySQL 8.4: столбец JSONInvalid 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 не пробел, поэтому поле из одних таких символов получит неожиданный символ.

Пустой 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 или {}.