Problems explained

Every error, warning and note Statac reports, what each means and how to fix it.

Every kind of problem Statac reports has a page here. The page’s name is the last part of the problem’s More: link, and running statac explain with that name shows the same page in the terminal.

Errors error 77 kinds

An error stops the build: nothing is published until it is fixed.

Alias limit: the aliases in a YAML file have repeated more than Statac will read.
Already a site: the folder given to statac new, or the folder statac import was to write the new site into, already contains a site.
Can’t listen: statac serve couldn’t open the port it serves the site on.
Can’t quieten: quiet: in statac.yaml lists a problem that can’t be quietened.
Can’t read: Statac couldn’t read a file or folder in the site.
Can’t remove: Statac couldn’t remove a folder it made, or a file in fetched/.
Can’t tell what made the site: statac import can’t tell which tool made the site in the folder it was given.
Can’t write: Statac couldn’t write one of the built site’s files.
Data named twice: two things in data/ would have the same name in templates.
Duplicate key: the same key is written twice at one level of some YAML or JSON.
Folder not empty: statac new, or statac import when it makes the new site, was given a folder that already has something in it.
Hook stopped: the command a hook runs, before_build or after_build in statac.yaml, didn’t succeed.
Language written twice: language in statac.yaml lists the same language twice.
Malformed call: Statac found what looks like a snippet call in your content, @name(...), but couldn’t read it.
Malformed JSON: Statac couldn’t read a JSON file in data/.
Malformed list: Statac can’t read a page’s posts: line, which chooses the posts the page lists.
Malformed maths: Statac found maths between dollar signs in your content, but couldn’t turn it into maths on the page.
Malformed record: a line in fetched/record, fetched/links or published.txt isn’t in the form Statac writes.
Malformed template: Statac couldn’t read a template or a snippet.
Malformed YAML: Statac couldn’t read some YAML.
Merge key: a data file uses <<, YAML’s merge key, to copy fields into an item from elsewhere in the file.
Missing command: the command line has options, but no command for them to apply to.
Missing content folder: a field in statac.yaml is declared as one of folder. followed by a path, but content/ has no folder at that path.
Missing data: a field is declared in statac.yaml as one of data. followed by a name, but nothing in data/ has that name.
Missing field: a page is missing a field that statac.yaml declares required, either for every page or for pages of the page’s type.
Missing file: a template uses css(), js() or asset() to ask for a file in assets/ that isn’t there, or a card’s settings refer to a background or font that isn’t in templates/og/.
Missing folder: statac import was run without the folder of the site to import.
Missing name: statac explain was run without a problem’s name.
Missing template: a page needs a template that isn’t in templates/.
Missing value: an option that needs a value was given without one.
Names nothing: a field that statac.yaml declares as one of data. and a table, or one of folder. and a folder, has a value that matches none of the names there.
Needs quotes: a text field has a value that YAML reads as something else, and reading it that way would change what you wrote.
Nested setting: one of Statac’s settings is written nested under its first part, such as layout: indented under pages:, or a text on a card is written as title: with text: under it.
Nested too deep: your Markdown is nested deeper than Statac will read.
No feed key: lists on the site ask for feeds, and statac.yaml has no feed_key.
No names to check: a field is declared in statac.yaml as one of data. followed by a table, but the table is written as a list.
No site here: a command that works on a site, such as statac build, found no site to work on.
No such date: a date is written in the right form, but no such date or time exists.
No value: a template shows or uses a value that doesn’t exist.
Not stamped: a value in a page’s front matter is still a stamp, such as =today or =monday 09:00.
Not Statac’s folder: the folder the built site should go in already contains files that Statac didn’t put there, or there is a file or link where the folder should be.
Not supported: a template or a page uses something Statac doesn’t support.
Nothing to search for: statac search was given no words.
Option given twice: the same option is given twice on the command line.
Other spelling: a field or setting uses a word that Statac spells differently, or a page’s content has a marker spelled differently, such as  for .
Output folder in the way: the output folder given to statac build with --out is one of the folders Statac reads the site from, or is inside one.
Outside the site: something in the site refers to a file outside the folder it is allowed to read from.
Redirect to itself: a page’s redirect_to is set to the page’s own URL, or to a URL whose redirects lead back to the page.
Reserved name: a custom setting, field or snippet uses a name that already has a meaning in Statac.
Retired file: the site still has fetched/refused, which Statac no longer reads.
Retired setting: statac.yaml has code_style, a setting Statac no longer reads.
Same id: two pages have the same id:.
Same translation: two pages in the same language would both be the translation of the same pages in the site’s other languages.
Same URL: two files would be published at the same URL.
Sass stopped: a Sass file in assets/ couldn’t be compiled to CSS.
Template stopped: a template failed while Statac was building a page with it, for a reason other than a missing value.
Text never shown: a template that extends another template fills a block that the other one doesn’t have, so the block’s contents don’t appear on any page.
Token in settings: statac.yaml has a webmention_token: line.
Two lists: a page has both each: and posts:.
Unclear date: a date is written with slashes or dots, so it could be read two ways.
Unclosed front matter: a Markdown file starts with a --- line, which opens front matter, but no later --- line closes it.
Unexpected argument: the command line includes a word that the command doesn’t use.
Unknown command: the first word after statac isn’t one of its commands.
Unknown option: the command line includes an option that the command doesn’t take.
Unknown problem name: a name given to quiet: in statac.yaml, or to statac explain, isn’t the name of any problem Statac knows.
Unknown word: Statac found a word it doesn’t know in a place where it knows every word that can be written.
Unknown YAML tag: a value in some YAML has a tag, written with !, that Statac doesn’t read.
Unreadable image: a page or its social card shows an image that Statac can’t use.
Unreadable name: a folder or path on the command line contains bytes that aren’t valid UTF-8.
Unusable card file: a social card’s settings name a background or a font that Statac can’t draw a card with.
Unusable date format: Statac can’t read the example date in date_format, or in a template’s date() filter.
Unusable name: a folder or path on the command line contains a control character, such as the escape character that starts a terminal’s colour codes.
Unusable URL: a URL can’t be written to disk, or a permalink pattern can’t make one.
Unwritable name: a file in assets/ or static/ has a name that some common disks can’t store.
Wrong argument: a snippet call hands the snippet something it can’t take, or leaves out something it reads.
Wrong kind of value: a field or setting has a different kind of value from the one it expects.
Wrong place: a setting is written somewhere it can’t take effect.

Warnings warning 58 kinds

A warning says what Statac did instead, and the build goes on.

Always false: a template uses is defined or is not defined to test whether a page has a field, but no page has a field with that name.
Broken external link: a link points at a page on another site, and when statac refresh last asked that site for the page, the answer showed the link is broken.
Broken link: a link, or a page’s redirect_to, points at a URL on this site, but nothing is published at that URL.
Cache not written: Statac couldn’t save something in .statac/.
Card not drawn: Statac couldn’t draw a page’s social card from what the page says, so the page has no card.
Cell never shown: a row in a table has more cells than the table has columns.
Code not coloured: a code block names a language that Statac colours, and one of its lines is longer than 5,000 characters.
Colon in call: an argument in a snippet call was named with a colon, as in caption: 'Post 1'.
Content never shown: a layout builds pages that have content, but never puts the content on the page, so each of those pages is published without it.
Content not published: a page with redirect_to has content after its front matter.
Control character: your content contains a control character.
Dates disagree: a page’s file name starts with a date, such as 2026-10-04-post-1.md, but its date: line has a different day.
Definition written twice: a page has two footnote definitions with the same label, such as two lines that start with [^1]:.
Describes no image: a file under content/ is named like an image’s sidecar file, such as photo-1.jpg.yaml, but there is no image of that name beside it.
Feed format mismatch: a feed’s file name says one format, but the feed is built as another, such as rss.xml built as an Atom feed.
Feed id changed: a post in a feed is now published at a different URL from the one the last build used, and it has no id: of its own.
Feed not written: a list asks for a feed, but Statac didn’t write it.
Feed written twice: a list’s feed: line names the same feed twice.
Field written two ways: a custom field is written with a dot in its name on one page, such as book.author:, and nested on another.
Footnote never shown: a page has a footnote definition, [^label]: The note., but no footnote reference in the content points at it.
HEIC image: a page shows an image saved as HEIC or HEIF, the format many phones save photos in.
Id used twice: a heading or a table has an id in braces, such as ## Title {#id} or a line of {#id} under a table’s last row, but something earlier on the page already has that id.
Images out of proportion: a stylesheet in assets/ has a rule for img that sets a max-width or a width for images, but no rule for img in any of the site’s stylesheets sets their height.
Language folder in pattern: a URL pattern for one language’s pages starts with that language’s folder.
Mention of no page: a webmention in fetched/mentions/ is for a URL on the site where nothing is published.
Missing anchor: a link points at a place on a page (the part after #) that isn’t there.
Missing definition: your content refers to a footnote, [^label], or to a link by its label, [text][label] or [label][], but no line on the page defines that label.
More written twice: a page’s content has  on a line of its own more than once.
No pages in language: language in statac.yaml declares a language that has no folder under content/.
No such line: a code block’s first line asks Statac to mark a line that the block doesn’t have, as mark=15 does on a block of 12 lines.
No thumbnail: a page shows a video hosted on YouTube or Vimeo with its thumbnail, but the site’s fetched/stills/ folder has no thumbnail for that video, so thumbnail is empty.
No time zone: the site’s settings don’t set a timezone, and some of its dates are written without an offset, such as 2026-10-04 or 2026-10-04 09:30.
No year pages: years.pages: true in statac.yaml asks for a page for each year, but no page has a date, so there is no year to publish a page for.
Not a post: a page with a date is at the URL of a list, such as a tag’s at /tags/rust/ or a folder’s at /notes/.
Not data: a file in data/ is neither YAML nor JSON.
Not linked by place: a page with no translation_key is in the same place as a page in another language that has one.
Nothing made: after_build_outputs lists a file or folder that the site’s after_build hook makes in the built site, but after the hook had run, nothing was there.
One tag, not two: a page’s tags are written on one line with commas between them and no brackets around them, such as tags: hills, water.
Output folder named: the site’s after_build hook contains the name of the folder the built site is published in.
Page in snippet: a snippet is handed a page, but it also shows a field of page.
Published as text: a page’s content contains something that Statac treats as ordinary text, though you may have meant something else, so the page shows it exactly as written.
Read as custom: a name that Statac treats as a custom field, setting or type is one slip away from a name that Statac or the site knows.
Sass warning: Sass printed a message while compiling a stylesheet in assets/.
Set aside: a page sets a field that Statac doesn’t use.
Size kept: a text on a card is placed at the top or the bottom, and its size is written with up to, as in up to 75.
Social image may not show: a page uses og_image to choose the social image it is shared with, and the file is in a format that some link previews don’t show, such as WebP or SVG.
Sorted last: a template sorts pages by a field with sort(attribute=...), and some of the pages it sorts don’t have that field.
Spelled two ways: your pages spell one tag, or one series, in two ways that give the same URL, such as Rust on some pages and rust on others.
Unknown code language: a code block gives its language as the first word after the opening fence, and Statac has no colours for that word.
Unknown language: the site’s language is set to a language Statac has no translations for, and the site’s languages/ folder has no file for it either.
Unmatched tag: HTML in a page’s Markdown, or in a value a template shows through the markdown filter, opens an element and never closes it, or closes an element it never opened.
Unmatched translation key: a page has a translation_key that no published page in another language has, so it isn’t linked to any translation.
Unordered pages: a list page sets its order as a list of names, order: [day-one, day-two], but the list has pages that aren’t named there.
Unused card: the site has settings for a social card, but no page is ever shared with it.
URL gone: a URL the site published before now has nothing at it.
URL taken: a draft, or a scheduled post, would be published at a URL that something else already uses.
Webmentions off: a template calls webmention(), which tells other sites where to send webmentions of your pages, but statac.yaml doesn’t have webmentions: true.
Worker outside the import map: a script in assets/ starts a worker, or loads a script into a worker, using the name of another file in assets/.

Notes note 27 kinds

A note tells you something about the published page. It doesn’t mean anything is wrong.

Built with page template: a home page or list page has content of its own, and the site has no template for that kind of page, so Statac built it with templates/page.html.
Built without template: the site has no template for some of its pages, so Statac published each of them as its content alone.
Call in HTML: a page contains HTML written by hand, and inside that HTML is @ followed by the name of one of the site’s snippets and an opening bracket, such as @book(.
Colour converted: an image has a colour profile other than sRGB, such as Display P3 or Adobe RGB.
Draft left out: a page has draft: true, so it isn’t built.
External link moved: a link points at a page on another site, and when statac refresh last asked for it, the site answered that the page has moved for good to another URL, which works.
Hook not run: the site sets a hook, before_build or after_build, in statac.yaml, and statac check doesn’t run it.
Location published: a JPEG, PNG or WebP image in content/ records where it was taken.
Loop over every page: a template loops over a list of all the site’s pages, such as site.pages or site.posts, and so many pages use it that the loops go through millions of pages between them.
Missing alt text: a page shows an image but has no alt text for a reader who can’t see it.
Missing button text: a <button> on a built page has nothing a screen reader can read out as its name.
Missing iframe title: an <iframe> on a built page has no title, and no aria-label or aria-labelledby either.
Missing label: a form control on a built page, an <input>, <select> or <textarea>, has no label.
Missing link text: a link on a built page has nothing a screen reader can read out as its name.
Missing title: a page built with a template has no <title>, or its <title> is empty.
Missing translation: a page is in a language with no translation for some of the text Statac adds to its content.
No home page: the site has pages, but nothing is published at its top, /, where a reader arrives from the site’s URL alone.
No language set: statac.yaml has no language setting, so Statac treats the site as written in English.
No list page: a folder, a tag or a series has posts, but nothing asks Statac to publish a list page for it, so it has none.
No site URL: the site has no full URL yet (url in statac.yaml), so Statac has left something that needs one out of the built site.
Numbered folder: every page in a folder has a name that starts with a number and a hyphen, such as 01-day-one.md, 02-day-two.md and 03-day-three.md, so Statac treats the folder as numbered.
Refused webmentions: refuse_webmentions_from in statac.yaml refuses some of the webmentions in fetched/mentions/, so no page shows them.
Robots beneath a path: the site is published beneath a path on its host, such as https://example.org/blog/, and it publishes a robots.txt.
Scheduled post: a post is dated after the day of the build, so Statac doesn’t publish it yet.
Untitled page: a template asked for a page’s name, either with headline(page) or as the title of a redirect, but the page has no name written.
Unused feed template: the site has a feed template, such as templates/feed.xml, but no list asks for a feed, so the template builds nothing.
Unused language file: the site has a file in languages/, such as languages/en-US.yaml, but Statac reads it for none of the site’s languages, so nothing in it is used.