Управляющий символ в 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.14 | Invalid control character at: line 1 column 17 (char 16). Перевод: «недопустимый управляющий символ: строка 1, колонка 17» | json.loads(text, strict=False) |
| Go 1.25–1.26 | invalid character '\n' in string literal. Перевод: «недопустимый символ \n в строковом литерале» | Нет |
| Go 1.27 | invalid character '\n' in string. Перевод: «недопустимый символ \n в строке» | Нет |
| Java, Jackson 2.15–2.23 | Illegal 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.3 | Control character error, possibly incorrectly encoded. Перевод: «ошибка управляющего символа, возможно, неверная кодировка» | Нет; код ошибки 3 |
| Rust, serde_json 1.0 | control character (\u0000-\u001F) found while parsing a string at line 2 column 0. Перевод: «при разборе строки найден управляющий символ» | Нет |
| jq 1.7.1 | Invalid string: control characters from U+0000 through U+001F must be escaped at line 2, column 9. Перевод: «неверная строка: символы от U+0000 до U+001F нужно экранировать» | Нет |
| MySQL 8.4: столбец JSON | Invalid 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.
- Неверный escape: обратный слэш с буквой, которой JSON не знает.
- Незакрытая строка: кавычка, которую так и не закрыли.
- Форматирование JSON: форматирование добавляет переводы строк между токенами, но никогда внутри строк.
- Все ошибки JSON
Управляющие символы в JSON: частые вопросы
Какие символы нужно экранировать в строке JSON?
Кавычку, обратный слэш и все символы от U+0000 до U+001F. У \b, \f, \n, \r и \t есть короткие формы, остальные пишутся как \u0000…\u001f.
Может ли строка JSON занимать несколько строк?
Не в набранном виде. Перевод строки внутри значения пишется как \n. Сам документ можно разнести на сколько угодно строк, но каждое строковое значение остаётся на одной.
Можно ли таб в JSON?
Между токенами — да, это обычный пробельный символ. Внутри строки — только экранированный, как \t.
Почему Safari пишет «Unterminated string»?
JavaScriptCore останавливается на голом управляющем символе и считает строку незаконченной. Закрывающая кавычка на месте; настоящая проблема — символ, на котором он остановился.