Основы · 7

Если что-то пошло не так

Почти все проблемы новичков — одни и те же: Docker не запущен, порт занят, файлы принадлежат не тому пользователю, страница лежит не в той папке. Здесь они собраны с решениями, а ниже каждый код ошибки сборки объяснён простыми словами.

Найдите своё сообщение на странице через Command и F (macOS) или Ctrl и F. Если его здесь нет, само сообщение сборки подскажет, что делать.

Простыми словами

Когда что-то идёт не так, HERON старается сказать три вещи: где (файл и строка), что не так и что сделать. Дочитайте сообщение до конца, прежде чем искать: последняя строка обычно и есть решение.

Проблемы приходят из трёх мест. Docker (не запускается, не может открыть порт). Ваши файлы (пропущенная кавычка, страница не в той папке, нет фото). Публикация (сайт не обновился, домен не открывается). Разделы ниже идут в этом порядке.

Когда нужна эта страница: когда команда не сработала или сайт выглядит не так. Когда можно пропустить: когда всё работает.

Docker и терминал

Cannot connect to the Docker daemon

Docker установлен, но не запущен.

macOS, Windows: Откройте Docker Desktop и дождитесь Engine running.
Linux: sudo systemctl start docker; чтобы стартовал вместе с компьютером: sudo systemctl enable docker.
Windows: Выполняйте команды HERON в терминале Ubuntu и проверьте в Docker Desktop Settings → Resources → WSL integration.

heron: command not found

Короткая команда heron не настроена в этом терминале.

Решение: Один раз выполните строку настройки со страницы С чего начать, затем откройте новое окно терминала.
bash или zsh: В macOS — zsh, в большинстве Linux и WSL — bash. Строка настройки должна попасть в файл вашей оболочки: ~/.zshrc или ~/.bashrc.
Проверка: heron --version печатает версию HERON.

Порт 8000 уже занят

Его занимает другая программа, часто прошлый просмотр.

Найдите её: lsof -i :8000 на macOS и Linux покажет программу.
Остановите старый просмотр: Перейдите в его терминал и нажмите Ctrl и C или закройте это окно.
Или перезапустите Docker: Выход из Docker Desktop и повторный запуск освобождают его порты.

Permission denied на файлы в папке сайта

Файлы создал Docker от имени администратора, и редактор не может их сохранить.

Почему: Когда-то HERON запустили без части --user в команде.
Решение: В папке сайта: sudo chown -R $(id -u):$(id -g) .
Чтобы не повторялось: Всегда используйте команду heron со страницы «С чего начать»: она запускается от вашего пользователя.

Страницы и файлы

Новая страница не появилась

HERON не нашёл файл или пропускает его.

Папка: Файл должен лежать внутри папки своего языка в content/ (например, content/en/), а не рядом.
Имя: Маленькие латинские буквы, цифры и дефисы, окончание .md: prices.md, about-us.md. Пробелы и заглавные нельзя.
Не скрытый: Файлы, которые начинаются с точки или подчёркивания (кроме _index.md), и README.md страницами не считаются.
published: Страница с published: false в настройках пропускается намеренно.

Страница есть, но её нет в меню

Меню — это список в site.yaml.

Решение: Добавьте ключ страницы — имя файла без .md — в nav: main: в site.yaml.
Название в меню: Берётся из nav_title в настройках страницы.

Текст слипся

Не хватает пустой строки.

Решение: Ставьте пустую строку перед каждым списком, заголовком, таблицей и блоком кода.
Проверка: Сравните с примерами в Markdown за 10 минут.

Блок выглядит не так, как ждали

Секция получила не ту форму: список вместо карточек, текст вместо таблицы.

Почему: HERON выбирает форму по тому, что внутри секции.
Решение: Сверьтесь с Формами секций или задайте форму классом: ## Тарифы {#plans .checklist}.

Коды ошибок сборки

Ошибка останавливает сборку. Сообщение начинается с кода, затем файл и строка.

Код	Что значит	Что сделать
E001	Сломан блок настроек вверху страницы	Проверьте кавычки, двоеточия и три дефиса в начале и конце блока
E002	Нет `title`, `h1` или `description`, или у поля значение не того вида	Заполните поле; дата — как 2026-10-19, `order` — число
E003	У двух секций в одном файле одинаковый якорь	Переименуйте один `{#якорь}`
E004	Два файла дают один адрес	Переименуйте файл или поменяйте его `slug`
E005	В имени файла или `slug` пробелы, заглавные или другие буквы	Только маленькие латинские буквы, цифры и дефисы
E006	Поле связи указывает на страницу, которой нет	Проверьте ключ страницы
E007	Фото упомянуто, но файла нет в `media/`	Проверьте имя файла и папку, включая заглавные буквы
E008	В теме нет шаблона для этого типа страницы	Проверьте `type` у страницы или спросите автора темы
E009	Старый адрес в `redirect_from` — адрес живой страницы	Уберите его из списка
E010	Тема просит значение, которого нет	Проблема темы: сообщите автору, приложите сообщение
E011	Ошибка в `site.yaml`	Прочитайте строку из сообщения; чаще всего отступ или пропущенная кавычка
E012	Версия HERON не подходит под строку `heron:` в `site.yaml`	Обновите HERON или осознанно поменяйте строку
E013	Тема из `site.yaml` не найдена	Проверьте имя темы и папку `theme/`
E014	Плагин из `plugins:` не установлен или упал	Установите его или уберите из списка
E015	HTML-теги на странице	Перепишите средствами Markdown и форм секций
E016	В якоре секции недопустимые символы	Маленькие латинские буквы, цифры и дефисы в `{#якорь}`
E017	В итоговой сборке нет ни одной страницы	Проверьте папку `content/`
E018	Фото лежат сразу в двух папках	Держите их только в `media/`
E019	У видео нет постера	Добавьте картинку-постер для видео
E020	Не собирается разметка для поисковиков	Заполните в `site.yaml` адрес или другие поля, названные в сообщении
E021	В основном языке нет страниц	Добавьте страницы в папку основного языка
E022	Удалённый адрес из `gone` принадлежит живой странице	Уберите его из `gone`
E023	Тема называет поля, которых HERON не знает	Проблема темы: сообщите автору

Предупреждения в итоговой сборке

Итоговая сборка (--strict) останавливается и на предупреждениях. Самые частые:

title длиннее 60 знаков, description длиннее 155. Сократите: поисковики обрезают длинные.
ссылка … никуда не ведёт. Ссылка в тексте ведёт на страницу, которой нет. Проверьте адрес или напишите ключ страницы, например /get-started/.
страница есть только на одном языке. Добавьте перевод или смиритесь, что ссылка ведёт на другой язык.
секция, которую тема не использует. Обычно опечатка в якоре.

Полный список сохраняется в .heron-cache/warnings.txt рядом с dist/.

Публикация

Сайт не обновился после git pushgit push спрашивает пароль и не принимает егоДомен не открывается или «не защищено»

Сборка на GitHub упала или ещё идёт.

Посмотрите. Вкладка Actions в репозитории: жёлтая точка — идёт, красный крестик — упала. Нажмите на неё и увидите то же сообщение, что и в своём терминале.
Исправьте и отправьте снова. Исправьте файл, затем git add . && git commit -m "Исправление" && git push.
Кэш браузера. Обновите страницу с зажатым Shift.

Вы правите страницу .mdВаш шаг
git commit и git pushВаш шаг
GitHub Actions собирает сайтАвтоматически
Проверяет, что сайт открываетсяАвтоматически
Образ уходит в реестрАвтоматически
Сервер берёт новый образ^¹Ваш шаг
Вы открываете сайт и проверяетеВаш шаг

Ваш шаг Автоматически · 3 из 7 шагов идут сами

¹ С HERON Агентом (платно) этот шаг идёт сам: Агент скачивает новый образ, меняет контейнер и откатывает, если проверка не прошла. На GitHub Pages он автоматический и так.

Пароль от аккаунта GitHub в терминале не принимает.

Решение. Вместо пароля вставьте токен. Как его создать: Git и GitHub.
Токен истёк. Создайте новый; старый продлить нельзя.

Аккаунт Docker Hub и токенВаш шаг
Вход с токеном: у себя и на сервереВаш шаг
Вы собираете сайтВаш шаг
Вы упаковываете его в образ и отправляетеВаш шаг
Сервер скачивает и запускает образ^¹Ваш шаг
Новый сайт работаетАвтоматически
Вы открываете сайт и проверяетеВаш шаг

Ваш шаг Автоматически · 1 из 7 шагов идёт сам

¹ С HERON Агентом (платно) последние шаги идут сами: он скачивает образ из вашего Docker Hub по вашему ключу и обновляет контейнер.

Не готовы DNS или сертификат.

Подождите. Новые DNS-записи расходятся за минуты, иногда за несколько часов.
Проверьте записи. Они должны точно совпадать с вашим хостингом: см. Ваш домен.
HTTPS. На GitHub Pages поставьте Enforce HTTPS, когда станет доступно; на сервере запустите certbot снова.

Вы собираете сайтВаш шаг
Вы проверяете его на localhostВаш шаг
Вы копируете dist/ на хостинг^¹Ваш шаг
Один раз: домен и HTTPSВаш шаг
Сайт работаетАвтоматически
Следующее обновление: снова собрать и скопироватьВаш шаг

Ваш шаг Автоматически · 1 из 6 шагов идёт сам: каждое обновление руками

¹ Куда: обычный хостинг или VPS (от €5 в месяц), или бесплатно на GitHub Pages и Cloudflare Pages.

Всё ещё не получается?

Скопируйте сообщение из терминала целиком, со строками над ошибкой, и создайте issue на GitHub. Напишите, какая у вас система и какую команду вы запускали. ИИ-ассистент тоже может прочитать сообщение и документацию вместе с вами.