Basics · 7

If something goes wrong

Most problems beginners meet are the same handful: Docker is not running, a port is busy, files belong to the wrong user, a page sits in the wrong folder. This page lists them with the fix, then explains every build error code in plain words.

Find your message below with Command and F (macOS) or Ctrl and F. If it is not here, the build message itself says what to do.

In plain words

When something goes wrong, HERON tries to say three things: where (file and line), what is wrong, and what to do. Read the message to the end before searching: the last line is usually the fix.

Problems come from three places. Docker (it does not start, it cannot open a port). Your files (a missing quote, a page in the wrong folder, a photo that is not there). Publishing (the site did not update, the domain does not open). The sections below follow that order.

When you need this page: when a command fails or the site looks wrong. When you can skip it: when it all works.

Docker and the terminal

Cannot connect to the Docker daemon

Docker is installed but not running.

macOS, Windows: Open Docker Desktop and wait for Engine running.
Linux: sudo systemctl start docker; to start it with the computer: sudo systemctl enable docker.
Windows: Run HERON commands in the Ubuntu terminal and check Settings → Resources → WSL integration in Docker Desktop.

heron: command not found

The short heron command is not set up in this terminal.

Fix: Run the setup line from Get started once, then open a new terminal window.
bash or zsh: macOS uses zsh, most Linux and WSL use bash. The setup line must go to the file of your shell: ~/.zshrc or ~/.bashrc.
Check: heron --version prints the HERON version.

Port 8000 is already in use

Another program, often an earlier preview, uses the port.

Find it: lsof -i :8000 on macOS and Linux shows the program.
Stop the old preview: Go to its terminal and press Ctrl and C, or close that window.
Or restart Docker: Quitting Docker Desktop and starting it again frees its ports.

Permission denied on files in the site folder

Files were created by Docker as the administrator, so your editor cannot save them.

Why: HERON was run without the --user part of the command at some point.
Fix: In the site folder: sudo chown -R $(id -u):$(id -g) .
Prevent: Always use the heron command from Get started, it runs as your user.

Pages and files

My new page does not appear

HERON did not find the file, or skips it.

Folder: The file must be inside the folder of its language in content/ (for example content/en/), not next to it.
Name: Small Latin letters, digits and dashes, ending in .md: prices.md, about-us.md. Spaces and capitals are not allowed.
Not hidden: Files starting with a dot or an underscore (except _index.md) and README.md are not pages.
published: A page with published: false in its settings is left out on purpose.

The page is there but not in the menu

The menu is a list in site.yaml.

Fix: Add the page's key, its file name without .md, to nav: main: in site.yaml.
Name in the menu: Comes from nav_title in the page settings.

The text looks glued together

A missing empty line.

Fix: Put an empty line before every list, heading, table and code block.
Check: Compare with the examples in Markdown in 10 minutes.

A block looks different from what I expected

The section got another form than you meant: a list instead of cards, text instead of a table.

Why: HERON chooses the form by what is inside the section.
Fix: Compare with Section forms, or set the form with a class: ## Plans {#plans .checklist}.

Build error codes

An error stops the build. The message starts with the code, then the file and the line.

Code	What it means	What to do
E001	The settings block at the top of a page is broken	Check quotes, colons and the three dashes at the top and bottom of the block
E002	`title`, `h1` or `description` is missing, or a field has the wrong kind of value	Fill the field; a date as 2026-10-19, `order` as a number
E003	Two sections in one file have the same anchor	Rename one `{#anchor}`
E004	Two files give the same address	Rename a file or change its `slug`
E005	A file name or `slug` has spaces, capitals or other letters	Use small Latin letters, digits and dashes
E006	A link field points to a page that does not exist	Check the page key
E007	A photo is mentioned but the file is not in `media/`	Check the file name and folder, including capital letters
E008	The theme has no template for this page type	Check `type` in the page or ask the theme author
E009	An old address in `redirect_from` is the address of a living page	Remove it from the list
E010	The theme asks for a value that does not exist	A theme problem: tell its author, with the message
E011	`site.yaml` has a mistake	Read the line given in the message; often an indent or a missing quote
E012	The HERON version does not fit the `heron:` line in `site.yaml`	Update HERON or change the line on purpose
E013	The theme in `site.yaml` is not found	Check the theme name and the `theme/` folder
E014	A plugin from `plugins:` is not installed or failed	Install it or remove it from the list
E015	HTML tags in a page	Rewrite with Markdown and section forms
E016	A section anchor has forbidden characters	Small Latin letters, digits and dashes in `{#anchor}`
E017	The final build has no pages at all	Check the `content/` folder
E018	Photos are in two folders at once	Keep them only in `media/`
E019	A video has no poster picture	Add a poster image for the video
E020	Structured data for search engines cannot be built	Fill the address or other fields the message names in `site.yaml`
E021	The main language has no pages	Add pages to the folder of the main language
E022	A removed address in `gone` belongs to a living page	Remove it from `gone`
E023	The theme names fields HERON does not know	A theme problem: tell its author

Warnings in the final build

The final build (--strict) stops on warnings too. The usual ones:

title longer than 60 characters, description longer than 155. Shorten them: search engines cut longer ones.
link … leads nowhere. A link in the text points to a page that does not exist. Check the address or write the page key, for example /get-started/.
page exists in one language only. Add the translation, or accept that the link leads to the other language.
section the theme does not use. Usually a typo in the anchor.

The full list is saved in .heron-cache/warnings.txt next to dist/.

Publishing

The site did not update after git pushgit push asks for a password and refuses itThe domain does not open or shows "not secure"

The build on GitHub failed or is still running.

Look. The Actions tab of the repository: a yellow dot is running, a red cross failed. Click it to see the same message as in your terminal.
Fix and push again. Fix the file, then git add . && git commit -m "Fix" && git push.
Browser cache. Refresh with Shift held down.

You edit a .md pageYour step
git commit and git pushYour step
GitHub Actions builds the siteAutomatic
It checks that the site opensAutomatic
The image goes to the registryAutomatic
The server takes the new image^¹Your step
You open the site and check itYour step

Your step Automatic · 3 of 7 steps run by themselves

¹ With HERON Agent (paid) this step runs by itself: the Agent pulls the new image, swaps the container and rolls back if the check fails. On GitHub Pages it is automatic anyway.

GitHub does not accept your account password in the terminal.

Fix. Paste a token as the password. How to create one: Git and GitHub.
Expired token. Create a new one; the old one cannot be extended.

Docker Hub account and a tokenYour step
Sign in with the token: here and on the serverYour step
You build the siteYour step
You pack it into an image and push itYour step
The server pulls and runs the image^¹Your step
The new site is liveAutomatic
You open the site and check itYour step

Your step Automatic · 1 of 7 steps runs by itself

¹ With HERON Agent (paid) the last steps run by themselves: it pulls the image from your Docker Hub with your key and updates the container.

DNS or the certificate is not ready.

Wait. New DNS records take minutes, sometimes a few hours.
Check the records. They must match your hosting exactly: see Your domain.
HTTPS. On GitHub Pages tick Enforce HTTPS when it becomes available; on a server run certbot again.

You build the siteYour step
You check it on localhostYour step
You copy dist/ to the hosting^¹Your step
Once: domain and HTTPSYour step
The site is liveAutomatic
Next update: build and copy againYour step

Your step Automatic · 1 of 6 steps runs by itself: every update is by hand

¹ Where: shared hosting or a VPS (from about €5 a month), or free on GitHub Pages and Cloudflare Pages.

Still stuck?

Copy the whole message from the terminal, including the lines above the error, and open an issue on GitHub. Say which system you use and which command you ran. An AI assistant can also read the message and the documentation with you.