ENRU

Управляющий символ в JSON: что значит «Bad control character in string literal» и как исправить

Обновлено

Перевод строки, нажатый Enter прямо внутри строки. JSON хочет его записанным как \n, а не набранным. Любой символ от U+0000 до U+001F (перевод строки, возврат каретки, таб и остальные) внутри строки JSON обязан быть экранирован, а голый останавливает парсер.

Перевод строки внутри строки JSON

Документ выглядит безобидно и падает везде. В значении стоит настоящий перевод строки, а не два символа \ и n:

{"msg":"line one
line two"}

В валидной версии вся строка на одной линии, а перевод записан escape-последовательностью. После разбора значение то же — две строки текста:

{"msg":"line one\nline two"}

Обычные подозреваемые: табы, вставленные из таблицы, \r из текста Windows, цветовые коды из логов терминала (они начинаются с U+001B, escape) и чаще всего JSON, склеенный из строк вместо сериализатора.

Почему JSON требует экранировать управляющие символы (RFC 8259)

RFC 8259, раздел 7 разрешает ставить в строку почти любой символ как есть. Исключения — кавычка, обратный слэш «and the control characters (U+0000 through U+001F)», то есть управляющие символы. Грамматика говорит то же: неэкранированный символ должен попасть в один из диапазонов ниже, а %x00-1F не входит ни в один.

unescaped = %x20-21 / %x23-5B / %x5D-10FFFF

У пяти управляющих символов есть короткие escape-последовательности: \b, \f, \n, \r, \t. Остальные пишутся как \u и четыре шестнадцатеричные цифры, например \u001b. Символ удаления (U+007F) и разделители строк Unicode U+2028 и U+2029 в запретный диапазон не входят: JSON принимает их как есть.

Ошибка «Bad control character» в разных парсерах

Ввод: плохой пример выше, перевод строки стоит на символе с индексом 16. Каждое сообщение получено запуском парсера 8 ноября 2026 года (Firefox — по исходникам SpiderMonkey). Третий столбец — переключатель, с которым парсер принимает голые управляющие символы, если такой есть.

ПарсерСообщениеМягкий режим
Chrome 156, Node 24–25 (V8)Bad control character in string literal in JSON at position 16 (line 1 column 17). Перевод: «недопустимый управляющий символ в строковом литерале JSON, позиция 16»Нет
Firefox (SpiderMonkey)bad control character in string literal. Перевод: «недопустимый управляющий символ в строковом литерале»Нет
Safari 27 (JavaScriptCore)JSON Parse error: Unterminated string. Перевод: «ошибка разбора JSON: незакрытая строка»Нет; сообщение сбивает с толку, строка дальше закрыта
Python 3.9–3.14Invalid control character at: line 1 column 17 (char 16). Перевод: «недопустимый управляющий символ: строка 1, колонка 17»json.loads(text, strict=False)
Go 1.25–1.26invalid character '\n' in string literal. Перевод: «недопустимый символ \n в строковом литерале»Нет
Go 1.27invalid character '\n' in string. Перевод: «недопустимый символ \n в строке»Нет
Java, Jackson 2.15–2.23Illegal unquoted character ((CTRL-CHAR, code 10)): has to be escaped using backslash to be included in string value. Перевод: «недопустимый неэкранированный символ (управляющий, код 10): в строке его нужно экранировать обратным слэшем»JsonReadFeature.ALLOW_UNESCAPED_CONTROL_CHARS
C#, System.Text.Json 10'0x0A' is invalid within a JSON string. The string should be correctly escaped.. Перевод: «0x0A недопустим в строке JSON, строку нужно правильно экранировать»Нет
C#, Newtonsoft.Json 13Ошибки нетГолые управляющие символы принимаются по умолчанию
PHP 8.3Control character error, possibly incorrectly encoded. Перевод: «ошибка управляющего символа, возможно, неверная кодировка»Нет; код ошибки 3
Rust, serde_json 1.0control character (\u0000-\u001F) found while parsing a string at line 2 column 0. Перевод: «при разборе строки найден управляющий символ»Нет
jq 1.7.1Invalid string: control characters from U+0000 through U+001F must be escaped at line 2, column 9. Перевод: «неверная строка: символы от U+0000 до U+001F нужно экранировать»Нет
MySQL 8.4: столбец JSONInvalid JSON text: "Invalid encoding in string." at position 16. Перевод: «неверный текст JSON: недопустимая кодировка в строке»Нет
Валидатор JSON StathamУправляющий символ в строке, строка 1, колонка 17Нет; код control_character

Позиции расходятся, потому что парсеры считают по-разному: V8 и Python считают символы с нуля, serde_json и jq уже относят сам перевод строки ко второй строке, а C# считает байты в строке. Указывают они все на один и тот же символ.

Как исправить управляющие символы в строках JSON

Надёжное исправление — на стороне, которая пишет JSON: пусть строку экранирует сериализатор. Чтобы спасти уже сломанный документ, strict=False в Python прочитает его, а json.dumps запишет обратно валидным. Все фрагменты запущены в таком виде.

JavaScript: шаблонная строка против JSON.stringify

const note = 'line one\nline two\tend';

const broken = `{"note":"${note}"}`;
const valid = JSON.stringify({ note });

console.log(valid); // {"note":"line one\nline two\tend"}

Python: починить сломанный документ

import json

data = json.loads(broken_text, strict=False)
fixed = json.dumps(data, ensure_ascii=False)
print(fixed)  # {"note": "line one\nline two\tend"}

Go

import "encoding/json"

func noteJSON(note string) ([]byte, error) {
	return json.Marshal(map[string]string{"note": note})
}

Java (Jackson)

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;

static String noteJson(ObjectMapper mapper, String note) throws JsonProcessingException {
    return mapper.writeValueAsString(Map.of("note", note));
}

C# (System.Text.Json)

using System.Text.Json;

var json = JsonSerializer.Serialize(new { note = "line one\nline two\tend" });
Console.WriteLine(json); // {"note":"line one\nline two\tend"}

PHP

$json = json_encode(['note' => "line one\nline two\tend"], JSON_THROW_ON_ERROR);
echo $json; // {"note":"line one\nline two\tend"}

Как не пускать голые управляющие символы

  • Не собирать JSON конкатенацией. Шаблоны, printf, echo в shell и строковые функции базы данных ничего не экранируют. JSON.stringify, json.dumps, json.Marshal, Jackson, JsonSerializer и json_encode экранируют каждый управляющий символ.
  • Вычищать цветовые коды из логов, прежде чем класть их в JSON: символ escape U+001B, с которого они начинаются, тоже управляющий.
  • Считать мягкий режим инструментом ремонта. strict=False в Python и флаг Jackson принимают ввод; результат стоит записать обратно сериализатором, чтобы следующему читателю не понадобился тот же флаг.
  • Держать каждую запись JSON Lines на одной строке. Голый перевод строки внутри значения режет запись надвое; подробнее — JSON Lines.

Найти управляющий символ в валидаторе

Попробовать: открыть пример с управляющим символом в валидаторе. Карточка ошибки называет символ, например «перевод строки (U+000A)» или «таб (U+0009)», а «Покажи» (F8) ставит на него курсор. Обратный слэш, за которым идёт голый перевод строки, получает тот же код: беда в голом символе, а не в escape.

Управляющие символы в JSON: частые вопросы

Какие символы нужно экранировать в строке JSON?

Кавычку, обратный слэш и все символы от U+0000 до U+001F. У \b, \f, \n, \r и \t есть короткие формы, остальные пишутся как \u0000…\u001f.

Может ли строка JSON занимать несколько строк?

Не в набранном виде. Перевод строки внутри значения пишется как \n. Сам документ можно разнести на сколько угодно строк, но каждое строковое значение остаётся на одной.

Можно ли таб в JSON?

Между токенами — да, это обычный пробельный символ. Внутри строки — только экранированный, как \t.

Почему Safari пишет «Unterminated string»?

JavaScriptCore останавливается на голом управляющем символе и считает строку незаконченной. Закрывающая кавычка на месте; настоящая проблема — символ, на котором он остановился.