Коды ошибок
Когда сборка или команда останавливается, Docara печатает код в квадратных скобках и короткое пояснение на английском:
[FRONT_MATTER_KEY_UNKNOWN] Supported keys: title, description, ... Source [content/ru/start.md], line [3], column [1].
Код не меняется между версиями и не зависит от языка, поэтому по нему удобно
искать. Пояснение после кода называет файл, строку или поле, где нужно
исправить ошибку. Команды с --json возвращают тот же код в списке диагностик, в поле code.
Исправляйте исходные файлы — Markdown, docara.json, section.json,
<page>.page.json, lang.json, redirects.json — и запускайте сборку
повторно. Не правьте результат в build_local или build_production:
следующая сборка его заменит.
Коды по разделам
| Раздел | Что там описано |
|---|---|
| Страницы и Markdown | Заголовок страницы (front matter), блоки Markdown, компоненты и их параметры, оглавление |
| Настройки сайта | Перенаправления, языки и переводы, поиск, фоновые эффекты, страница 404, адрес сайта, тема, бренд, портал |
| Обновление Docara | Команда upgrade и её откат |
| Проверка сборки | Отметки verify-static, начинающиеся с @ |
Общие коды
Эти коды встречаются в любом проекте: они проверяют файлы настроек и структуру каталога.
| Код | Причина и что сделать |
|---|---|
JSON_INVALID |
Файл настроек не является корректным JSON: лишняя или пропущенная запятая, одинарные кавычки, комментарий. Что сделать: Откройте файл из сообщения и исправьте синтаксис. Редактор с проверкой JSON покажет точное место. |
JSON_OBJECT_REQUIRED |
В файле не объект {...}, а массив, строка или число. Что сделать: Оберните настройки в фигурные скобки. |
SCHEMA_VALIDATION_FAILED |
Поле неизвестно, имеет неверный тип или значение вне списка. В сообщении указан JSON Pointer поля, например /settings/theme. Что сделать: Сверьте поле со справочником настроек сайта, раздела или страницы. Удалите поля, которых нет в справочнике. |
FILE_NOT_FOUND |
Нет обязательного файла: docara.json или файла, на который он ссылается, например simai-framework.lock.json. Что сделать: Запустите команду из каталога сайта или восстановите файл. Путь в framework_lock отсчитывается от каталога сайта. |
SYMLINK_FORBIDDEN, ROOT_SYMLINK_FORBIDDEN |
Путь к содержимому или сам каталог сайта проходит через символическую ссылку. Что сделать: Замените ссылку настоящим каталогом или файлом. Docara не идёт по ссылкам, чтобы сборка не читала файлы вне проекта. |
PATH_ESCAPE_FORBIDDEN |
Путь из настроек ведёт за пределы каталога сайта, например через ../. Что сделать: Укажите путь внутри проекта. |
CONTENT_ROOT_INVALID, CONTENT_ROOT_NOT_FOUND |
content_root пустой, небезопасный или указывает на несуществующий каталог. Что сделать: Укажите относительный путь к существующему каталогу с Markdown, например content. |
PAGE_EXTENSION_INVALID |
Страница имеет расширение, отличное от .md или .markdown. Что сделать: Переименуйте файл. |
PAGE_OUTSIDE_CONTENT_ROOT |
Страница лежит вне content_root. Что сделать: Перенесите страницу в каталог содержимого или исправьте content_root. |
PORTABLE_OUTPUT_COLLISION, PAGE_SOURCE_ROUTE_AMBIGUOUS |
Две страницы дают один и тот же адрес, например guide.md и guide/index.md. Что сделать: Оставьте одну из них или переименуйте вторую. |
FILE_INVALID |
Путь из настроек указывает не на обычный файл, например на каталог. Что сделать: Укажите путь к файлу. |
PAGE_SOURCE_EXTENSION_INVALID |
В каталоге содержимого лежит страница не с расширением .md. Что сделать: Переименуйте файл в .md. |
PAGE_SOURCE_PATH_INVALID, PAGE_SOURCE_OUTSIDE_LOCALE_ROOT |
Путь страницы содержит .. или выходит за каталог языка. Что сделать: Положите страницу внутрь каталога языка. |
PAGE_SOURCE_LOCALE_ROOT_MISSING |
Каталога содержимого языка из locales нет. Что сделать: Создайте каталог или исправьте content_root языка. |
PAGE_SOURCE_SYMLINK_FORBIDDEN |
В каталоге содержимого есть символическая ссылка. Что сделать: Замените её настоящим файлом или каталогом. |
PAGE_SLUG_INVALID |
slug страницы содержит недопустимые символы или ... Что сделать: Используйте строчные латинские буквы, цифры, - и /. |
PAGE_SLUG_RESERVED |
slug занимает служебный адрес Docara, например _docara. Что сделать: Выберите другой адрес. |
PAGE_DRAFT_NOT_PUBLISHED |
Сборка одной страницы (--page) запрошена для черновика с draft: true. Что сделать: Снимите draft или соберите другую страницу. |
PAGE_ROUTE_UNKNOWN |
Команда получила адрес, которому не соответствует ни одна страница. Что сделать: Проверьте адрес: он начинается и заканчивается на /, например /ru/start/. |
SECTION_DESCRIPTOR_LEGACY_NAME |
Найден файл раздела со старым именем _section.json. Что сделать: Переименуйте его в section.json. Не держите оба файла. |
COMPOSITION_RECIPE_RUNTIME_REQUIRED |
Не найдена команда node или код композиции страниц SIMAI Framework. Сборке нужен Node.js 20 или новее, готовому сайту — нет. Что сделать: Установите Node.js 20 или новее либо укажите путь в переменной DOCARA_NODE_BINARY. |
PORTABLE_PAGE_TRANSFORM_FAILED |
Команда из page_transforms завершилась с ошибкой. В сообщении есть её код выхода и вывод. Что сделать: Исправьте команду или её входные данные. Команда получает каталог собранного сайта последним аргументом. |
PORTABLE_INCREMENTAL_BASE_MISSING |
Сборка одной страницы (--page) запущена без готовой полной сборки. Что сделать: Сначала выполните полную сборку без --page. |
AUTHORING_JSON_INVALID, AUTHORING_SCHEMA_INVALID, AUTHORING_FILE_UNSAFE, AUTHORING_RULE_CONFLICT, AUTHORING_PROFILE_UNKNOWN |
Ошибка в docara.authoring.json: неверный JSON, ссылка вместо файла, два правила с разными профилями для одной страницы или неизвестный профиль. Что сделать: См. Профили страниц. |
PAGE_PROFILE_ONE_H1_MISSING, PAGE_PROFILE_INTRODUCTION_MISSING, PAGE_PROFILE_MULTIPLE_SECTIONS_MISSING, PAGE_PROFILE_MAIN_MATERIAL_MISSING, PAGE_PROFILE_ORDERED_STEPS_MISSING, PAGE_PROFILE_STRUCTURED_REFERENCE_MISSING, PAGE_PROFILE_ACTION_MISSING |
Предупреждение docara validate page: странице не хватает части, которую требует её профиль. Сборка продолжается. Что сделать: Добавьте недостающую часть или смените профиль. См. Профили страниц. |
PAGE_EDITORIAL_REVIEW_REQUIRED |
Напоминание docara validate page: смысловые вопросы профиля проверяет человек. Что сделать: Пройдите список вопросов из отчёта. Это не ошибка. |
QA_DRY_RUN_REQUIRED |
docara qa запущена без --dry-run и точной --page. Что сделать: Запустите docara qa --dry-run --page=<адрес>. |
Если кода нет в справочнике
Справочник начинается с кодов, которые чаще всего встречают авторы и владельцы
сайта. Остальные коды — внутренние проверки сборки, Smart-компонентов и
Framework lock — пока описаны только сообщением в самой ошибке. Список
неописанных кодов хранится в репозитории Docara в файле
docs/diagnostic-code-coverage.json и обновляется вместе с кодом.
Если код не описан, прочитайте пояснение после него: там почти всегда есть имя файла и поля. Если этого мало, откройте решение проблем или задайте вопрос в репозитории Docara и приложите полный текст ошибки.