Ошибка «недопустимые данные на корневом уровне: строка 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. После этого перезапустите программу и проверьте, исчезла ли ошибка.
Шаг 2. Проверка содержимого: JSON это или нет
Частая ситуация при работе скриптов и программ, скачивающих данные: вместо ожидаемого JSON-ответа в файл попадает HTML. Откройте файл и посмотрите на первые символы. Если видите <!DOCTYPE html> или <html> — перед вами страница ошибки сервера, а не данные.
Валидный JSON на корневом уровне обязан начинаться с одного из двух символов:
- 📦
{— начало объекта; - 📋
[— начало массива.
Всё остальное — текст, число вне структуры, служебная строка — вызовет ошибку разбора. Также проверьте, нет ли перед скобкой вывода отладки: строки вроде Warning:, Notice: или случайного echo в серверном скрипте ломают ответ целиком.
// Пример корректного начала JSON-файла
{
"setting": "value",
"enabled": true
}
Быстрая проверка JSON: вставьте содержимое файла в любой онлайн-валидатор JSON — он укажет точную позицию первой синтаксической проблемы.
Шаг 3. Пустой или повреждённый файл
Проверьте размер файла в проводнике. Нулевой размер означает, что данные не были записаны: возможная причина — прерванное сохранение, сбой диска, нехватка места или принудительное завершение программы в момент записи. Парсер, получив пустой ввод, сообщает об ошибке именно в позиции 1:1, потому что дальше идти некуда.
Если файл конфигурации обнулён, восстановить его можно из резервной копии программы (многие приложения хранят .bak-версию рядом с основным файлом), из облачной синхронизации или удалив файл — тогда программа при следующем запуске создаст конфигурацию по умолчанию. Последний вариант приведёт к сбросу настроек, что нужно учитывать.
☑️ Диагностика файла с ошибкой
Шаг 4. Ошибка в XML-документах
Для XML правила строже: документ должен начинаться с декларации <?xml version="1.0" ...?> или сразу с корневого тега, и до них не допускается ничего — даже пробела или пустой строки. Именно ведущий перевод строки перед декларацией — одна из самых коварных причин, потому что визуально файл выглядит нормально.
Также проверьте, что в файле ровно один корневой элемент. Два тега верхнего уровня подряд дадут ошибку разбора, хотя и не всегда в позиции 1:1. Самая частая причина именно позиции 1:1 в XML — невидимый BOM или пустая строка перед декларацией, оставленная редактором или шаблонизатором.
⚠️ Внимание: если файл генерируется скриптом, править его вручную бессмысленно — при следующей генерации ошибка вернётся. Ищите источник лишнего вывода в коде: лишний пробел до открывающего тега скрипта или отладочный вывод.
Сводная таблица причин и решений
| Что видно в начале файла | Вероятная причина | Решение |
|---|---|---|
| Невидимый символ, кодировка UTF-8 with BOM | Метка порядка байтов | Пересохранить в UTF-8 без BOM |
| <!DOCTYPE html> или <html> | Сервер вернул страницу ошибки вместо данных | Проверить запрос, URL и доступность API |
| Ничего, размер 0 байт | Файл не записан или обнулён | Восстановить из копии или удалить для пересоздания |
| Warning, Notice, текст ошибки | Отладочный вывод скрипта в ответе | Отключить вывод ошибок в коде |
| Пустая строка перед <?xml | Ведущий перевод строки в XML | Удалить все символы до декларации |
Почему ошибка возникает «из ниоткуда» после обновления программы
Обновлённая версия могла сменить формат конфигурации или строгость парсера. Файл, который старая версия читала с допущениями, новая отклоняет. Решение — переименовать старый конфиг, дать программе создать новый и перенести настройки вручную.
Когда ошибка появляется в конкретной программе
Если сообщение выдаёт конкретное приложение при запуске, значит, повреждён его файл настроек или кэш. Универсальный безопасный порядок такой: закройте программу, найдите её конфигурационный файл (обычно в профиле пользователя или папке приложения), переименуйте его, добавив .old, и запустите программу снова. Она создаст чистый файл настроек.
Если после этого программа запустилась — причина подтверждена, и остаётся перенести нужные параметры из старого файла, открыв оба в редакторе. Если ошибка сохраняется и с новым конфигом — проблема глубже: проверьте целостность установки программы и наличие обновлений. Точное расположение файлов настроек зависит от конкретного приложения, поэтому сверяйтесь с его документацией.
Ошибка «строка 1, позиция 1» — это всегда проблема самого начала файла: BOM, лишний текст, пустой файл или HTML вместо данных. Диагностика занимает минуты, если открыть файл в редакторе с показом служебных символов.
FAQ: частые вопросы
Что значит «корневой уровень» в этой ошибке?
Это верхний уровень структуры документа. В JSON там допустим один объект или массив, в XML — декларация и один корневой тег. Любой символ, который парсер не ожидает в этой позиции, вызывает ошибку разбора.
Файл выглядит нормально, но ошибка остаётся. Что делать?
Скорее всего, в начале файла есть невидимый символ — чаще всего BOM. Откройте файл в Notepad++ или VS Code, проверьте кодировку и пересохраните как UTF-8 без BOM. Также включите отображение всех символов, чтобы увидеть скрытые пробелы или переносы строк.
Можно ли исправить ошибку, не разбираясь в JSON?
Да, если причина в BOM или пустом файле — пересохранение в правильной кодировке или восстановление файла из копии не требует знания формата. Для правки синтаксиса используйте онлайн-валидатор: он покажет позицию проблемы.
Ошибка появляется при загрузке данных из интернета. Файл на диске в порядке?
Тогда проблема в ответе сервера: вместо JSON программа получает HTML-страницу ошибки или пустой ответ. Проверьте доступность адреса в браузере, корректность запроса и не требует ли сервер авторизации или обновления версии программы.
Опасно ли удалять повреждённый файл конфигурации?
Удаление или переименование конфига обычно безопасно: программа создаст новый с настройками по умолчанию. Но пользовательские настройки будут потеряны, поэтому сначала сделайте копию файла — из неё можно будет восстановить параметры вручную.