ENRU

Метка BOM в JSON: что значит «Unexpected UTF-8 BOM» и как исправить

Обновлено

Три невидимых байта в самом начале файла. Ты их не видишь, парсер — видит. Метку порядка байтов (BOM, U+FEFF) ставят перед текстом в UTF-8 некоторые редакторы и программы Windows, и большинство парсеров JSON такой документ не принимают.

Как выглядит BOM перед JSON

В редакторе файл безупречен. А в байтах перед первой скобкой стоят EF BB BF — так U+FEFF записывается в UTF-8. Любая из двух команд покажет первые три байта: при BOM od напечатает ef bb bf, а Python — b'\xef\xbb\xbf'.

head -c 3 data.json | od -An -tx1
python3 -c "print(open('data.json', 'rb').read(3))"

Без этих трёх байтов тот же документ валиден. Больше в файле ничего не меняется: BOM никогда не был частью данных.

{"a":1}

Что RFC 8259 говорит о BOM

RFC 8259, раздел 8.1 высказывается непривычно прямо: реализации не должны добавлять метку порядка байтов в начало JSON, который передаётся по сети. Следующая фраза разрешает парсерам её игнорировать «in the interests of interoperability», то есть ради совместимости. Это разрешение, а не обязанность.

JSON передаётся в UTF-8, где порядка байтов нет, так что BOM не несёт никакой информации. А раздел 2 разрешает перед значением ровно четыре пробельных символа, и U+FEFF среди них нет. Поэтому строгий парсер BOM отвергает, мягкий пропускает, и оба в рамках стандарта. Отсюда и картина, когда файл открывается в jq и падает в JSON.parse.

Ошибки BOM в разных парсерах

Ввод: байты EF BB BF и следом {"a":1}; для строковых API — строка, начинающаяся с U+FEFF. Каждое сообщение получено запуском парсера 8 ноября 2026 года, у Firefox — взято из исходников SpiderMonkey. Третий столбец — что будет, если прочитать такой файл обычным способом. В нескольких сообщениях BOM стоит прямо между кавычками: он там есть, просто его не видно.

ПарсерСообщение на BOM в началеЧтение файла с BOM
Chrome 156, Node 24–25 (V8)Unexpected token '', "{"a":1}" is not valid JSON. Перевод: «неожиданный токен, это не валидный JSON»readFileSync(path, "utf8") оставляет BOM; TextDecoder и response.json() в Node его убирают
Firefox (SpiderMonkey)unexpected character. Перевод: «неожиданный символ»По исходникам; строка 1, колонка 1
Safari 27 (JavaScriptCore)JSON Parse error: Unrecognized token ''. Перевод: «ошибка разбора JSON: нераспознанный токен»Без позиции
Python 3.9–3.14: json.loads(str)Unexpected UTF-8 BOM (decode using utf-8-sig): line 1 column 1 (char 0). Перевод: «неожиданная метка BOM UTF-8 (декодируйте через utf-8-sig)»encoding="utf-8-sig" и json.loads(bytes) её пропускают
Go 1.25–1.26invalid character 'ï' looking for beginning of value. Перевод: «недопустимый символ “ï” там, где ожидалось начало значения»ï — первый байт BOM, прочитанный отдельно; os.ReadFile BOM оставляет
Go 1.27invalid character '\ufeff' looking for beginning of value. Перевод: то же, но символ назван точноПричина та же
Java, Jackson 2.15–2.23 (ввод строкой)Unexpected character ('' (code 65279 / 0xfeff)): expected a valid value (JSON String, Number, Array, Object or token 'null', 'true' or 'false'). Перевод: «неожиданный символ, ожидалось допустимое значение»Ввод byte[] BOM пропускает
C#, System.Text.Json 10'0xEF' is an invalid start of a value. LineNumber: 0 | BytePositionInLine: 0.. Перевод: «0xEF не может начинать значение»File.ReadAllText BOM убирает, File.ReadAllBytes — оставляет
C#, Newtonsoft.Json 13Unexpected character encountered while parsing value: . Path '', line 0, position 0.. Перевод: «при разборе значения встретился неожиданный символ»Невидимый BOM напечатан после двоеточия
PHP 8.3: json_decodeSyntax error. Перевод: «синтаксическая ошибка»file_get_contents BOM оставляет
Rust, serde_json 1.0expected value at line 1 column 1. Перевод: «ожидалось значение»В сообщении ни намёка на BOM
jq 1.7.1Ошибки нетjq пропускает BOM в начале
MySQL 8.4: столбец JSONInvalid JSON text: "Invalid value." at position 0. Перевод: «неверный текст JSON: недопустимое значение, позиция 0»Позиция 0 — первый байт BOM
Валидатор JSON StathamМетка BOM, строка 1, колонка 1Код bom; открытый файл сохраняет BOM, и его видно

Как убрать BOM перед разбором JSON

Срезать U+FEFF в начале текста или поручить это чтению файла. Каждый фрагмент запущен на файле с BOM и так же работает с файлами без него.

JavaScript (Node.js)

import { readFileSync } from 'node:fs';

const text = readFileSync('data.json', 'utf8');
const data = JSON.parse(text.replace(/^\uFEFF/, ''));

Python

import json

with open("data.json", encoding="utf-8-sig") as f:
    data = json.load(f)

utf-8-sig читает UTF-8 и с BOM, и без него, поэтому это надёжное умолчание для чужих файлов JSON. Документация модуля json отмечает, что json.loads принимает и байты и сам определяет кодировку.

Go

import (
	"bytes"
	"encoding/json"
	"os"
)

func loadJSON(path string, v any) error {
	data, err := os.ReadFile(path)
	if err != nil {
		return err
	}
	data = bytes.TrimPrefix(data, []byte("\xef\xbb\xbf"))
	return json.Unmarshal(data, v)
}

Java (Jackson)

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

static JsonNode load(ObjectMapper mapper, Path path) throws IOException {
    return mapper.readTree(Files.readAllBytes(path));
}

static JsonNode parse(ObjectMapper mapper, String text) throws IOException {
    return mapper.readTree(text.replaceFirst("^\uFEFF", ""));
}

C# (System.Text.Json)

using System.Text.Json;

var text = File.ReadAllText("data.json");
using var doc = JsonDocument.Parse(text.TrimStart('\uFEFF'));

File.ReadAllText сам находит и убирает BOM; TrimStart нужен для текста, пришедшего другим путём. Байты, переданные прямо в JsonDocument.Parse, никто не чистит — отсюда и 0xEF.

PHP

$text = file_get_contents('data.json');
$text = preg_replace('/^\xEF\xBB\xBF/', '', $text);
$data = json_decode($text, true);

Откуда берётся BOM и как от него избавиться

  • Windows PowerShell 5.1. -Encoding UTF8 там означает UTF-8 с BOM. PowerShell 6 и новее по умолчанию пишут UTF-8 без метки (about_Character_Encoding); в 5.1 писать через [System.IO.File]::WriteAllText($path, $json).
  • Редакторы. Блокнот при сохранении предлагает и «UTF-8», и «UTF-8 с BOM». В VS Code кодировка видна в строке состояния: щёлкнуть по ней, выбрать сохранение с кодировкой и UTF-8.
  • C#. File.WriteAllText(path, text) пишет без BOM; Encoding.UTF8 третьим аргументом метку добавляет.
  • Python. encoding="utf-8-sig" при записи ставит BOM. Его место — только чтение.
  • Проверка в CI. Если head -c 3 file.json | od -An -tx1 печатает ef bb bf, пусть сборка упадёт раньше, чем строгий парсер в бою.

Найти BOM в валидаторе

Попробовать: открыть пример с BOM в валидаторе. Открытый файл сохраняет свой BOM, поэтому валидатор сообщает bom в строке 1, колонке 1, а не прячет проблему. Остаётся нажать «Покажи» (F8), затем Delete. U+FEFF дальше в документе уже не метка порядка байтов, а просто невидимый символ между токенами: он получит неожиданный символ. Внутри строки это обычный символ, и он валиден.

BOM в JSON: частые вопросы

Можно ли BOM в JSON?

Не в том JSON, который отправляется: RFC 8259 запрещает реализациям добавлять метку в JSON для сети. Парсерам разрешено её игнорировать, поэтому одни принимают, но JSON.parse, json.loads в Python на строке и Go отвергают.

Как узнать, есть ли в файле BOM?

Посмотреть на первые три байта: EF BB BF — это BOM в UTF-8. В Linux и macOS: head -c 3 file.json | od -An -tx1; в VS Code строка состояния покажет «UTF-8 with BOM».

Что значит «decode using utf-8-sig» в Python?

Это название кодека, который пропускает BOM. Открыть файл с encoding="utf-8-sig" или передать в json.loads сырые байты: он сам распознает метку.

Меняет ли удаление BOM данные?

Нет. BOM не входит ни в одно значение, и без него документ тот же. А U+FEFF внутри строки — это данные, они остаются.