Ошибка «недопустимые данные на корневом уровне: строка 1, позиция 1» означает, что парсер не смог распознать самый первый символ файла — чаще всего это JSON- или XML-документ, который программа пытается прочитать при загрузке конфигурации, импорте данных или открытии проекта. Сбой возникает до анализа содержимого: интерпретатор ожидает открывающую скобку {, квадратную скобку [ или декларацию <?xml, а встречает что-то другое.

Типичный сценарий: приложение при запуске читает файл настроек, получает в ответ HTML-страницу ошибки сервера, пустой файл или текст с невидимым служебным символом — и прерывает работу с этим сообщением. Ниже разберём, как локализовать источник проблемы и исправить файл без потери данных.

Что означает сообщение об ошибке

Формулировка указывает на лексический уровень разбора: парсер ещё не дошёл до проверки структуры, он споткнулся о первый байт. «Корневой уровень» — это верхний уровень документа, где в JSON допустим только один корневой элемент (объект или массив), а в XML — декларация и единственный корневой тег.

«Строка 1, позиция 1» говорит о том, что проблема находится в самом начале файла. Это важная подсказка: искать ошибку в середине или конце документа не нужно. Достаточно открыть файл в редакторе, который показывает служебные символы, и посмотреть, что реально стоит перед первым видимым знаком.

Откройте проблемный файл в редакторе вроде Notepad++ или VS Code и включите отображение всех символов. Если перед содержимым видны неожиданные знаки, пробелы, пустые строки или «мусор» — причина найдена.

Основные причины появления ошибки

Практика показывает, что к этому сообщению приводит ограниченный набор ситуаций. Проверять их стоит в порядке от самых частых к редким:

  • 🔤 BOM (Byte Order Mark) — невидимая метка порядка байтов в начале файла в кодировке UTF-8 с BOM; некоторые парсеры воспринимают её как недопустимый символ.
  • 📄 Файл содержит не JSON/XML, а HTML-страницу ошибки (например, ответ сервера 404 или 500), которую программа сохранила как данные.
  • 🕳️ Файл пустой или обрезан при сохранении, скачивании или сбое записи на диск.
  • 💬 Перед корневым элементом стоят комментарии, пробелы, текст или вывод отладочной информации (типично для ответов скриптов).
  • 🔀 Повреждение файла при копировании, синхронизации облаком или работе антивируса.
⚠️ Внимание: прежде чем редактировать файл конфигурации, сделайте его копию. Если это файл настроек программы или проекта, ошибочная правка может привести к сбросу конфигурации, и восстановить её будет нечем.

Шаг 1. Проверка начала файла и кодировки

Первое действие — открыть файл в редакторе с отображением кодировки. В Notepad++ текущая кодировка показана в строке состояния, в VS Code — в правом нижнем углу. Если указано UTF-8 with BOM, а программа ожидает чистый UTF-8, это вероятный источник сбоя.

Пересохраните файл без BOM: в Notepad++ это делается через меню Кодировки → Преобразовать в UTF-8 без BOM, затем сохранение. В VS Code достаточно кликнуть по названию кодировки в строке состояния и выбрать сохранение в plain UTF-8. После этого перезапустите программу и проверьте, исчезла ли ошибка.

📊 Где вы столкнулись с этой ошибкой?