Statac

Errors, warnings and notes

Read a problem Statac reports, see what each kind means, and quieten one.

When something in your site needs attention, Statac tells you what, where, and what to do about it. This page shows how to read those messages, what the three levels mean, and how to quieten a kind you’ve dealt with. Problems explained has a page for every kind of problem.

How a problem looks

warning  Broken link: nothing is published at `/about-us/`
  content/post-1.md, line 5
   5 │ Read more [about us](/about-us/).
     │                      ^^^^^^^^^^
  Did you mean `/about/`?
  More: https://statac.dev/e/broken-link/
Part What it says
warning Broken link: ... The kind of problem, then what happened. Your own text is in backticks.
content/post-1.md, line 5 The file and the line.
5 │ and ^ The line itself. The ^ marks under it show the exact text.
Did you mean ...? What to do about it. This line appears only when there’s a good suggestion.
More: A link to a page about that kind of problem. It’s always there.

If a problem isn’t in a file, such as a full disk, the message says what Statac was doing instead of giving a file and line.

To read the More: page in the terminal instead, see read about a kind in the terminal.

Errors, warnings and notes

Kind What it tells you The build
error What made Statac stop. Stops. Statac publishes nothing, and _site keeps what the last build wrote.
warning What Statac did instead of what you wrote. Carries on.
note Something about the published site you may want to know, such as a draft left out or an image with no alt text. Carries on.

In short: if Statac is sure what you meant, it does that and gives a warning. If it isn’t sure, it stops with an error.

A command that an error stops exits with code 1, or with code 2 if the mistake is in the command line. Warnings and notes leave the code at 0. See exit codes.

A bug in Statac itself is none of these. For a bug, Statac exits with code 101 and prints Rust’s own report, which ends with Report it at https://git.statac.dev/statac/statac/issues, with the lines above.

What does build show?

3 warnings: 2 dates-disagree, 1 broken-link.
3 notes: 2 no-site-url, 1 missing-title. Run `statac check` to see them.

Made 8 resized copies of 1 image.
Wrote 7 pages and 9 other files to `_site` in 0.10 seconds.

statac build keeps its output short. It counts the warnings and the notes by kind, on a line each, and shows only errors in full:

error  Missing file: there is no `assets/sit.css`
  templates/base.html, line 6
   6 │   {{ css("sit.css") }}
     │      ^^^^^^^^^^^^^^
  While building: content/about.md
  And while building 6 more:
    content/index.md
    content/now.md
    content/posts/2026-10-04-post-1.md
    content/posts/2026-10-11-post-2.md
    content/posts/2026-10-18-post-3.md
    and 1 more. Run `statac check` to see it.
  Did you mean `site.css`?
  More: https://statac.dev/e/missing-file/

2 warnings: 2 dates-disagree.
2 notes: 2 no-site-url. Run `statac check` to see them.

Wrote nothing: 1 error stopped the build.

If a mistake in a template breaks many pages, it’s reported once, naming the first page it broke and up to five more.

One warning is the exception, and build shows it in full, because only a build can find it: nothing made.

What does check show?

statac check

check is the command for seeing everything. It builds the site the same way as build, but writes nothing and runs no hooks. It shows every problem in full, with every page where it happened, then counts them the same way as build.

Four notes appear only in check: hook not run, location published, no home page and no list page. If there is nothing to report, it prints No problems.

It also lists the JavaScript the site carries:

JavaScript the site carries:
  `/app.c54ed596.js` from `assets/app.js`, on 3 pages

Quieten a kind you have understood

In statac.yaml:

quiet: [dates-disagree]
1 warning: 1 broken-link, and 2 quietened.
3 notes: 2 no-site-url, 1 missing-title. Run `statac check` to see them.

Once you’ve understood a kind of warning or note and decided it’s fine, add its name to quiet. check then stops showing those problems, but build and check still count them, as 2 quietened shows above. If every warning, or every note, is quietened, its line says so: 3 warnings, all quietened.

The name of a kind is the last part of its More: link.

You can’t quieten an error, or a problem that leaves a page out, such as a draft left out.

Read about a kind in the terminal

statac explain broken-link

statac explain takes the kind’s name, the last part of its More: link, and prints the page that link goes to, without going online.

What Statac checks in each built page

Statac reads every page it builds and points out common accessibility gaps, with a note for each of these:

On a built page Note
An image with no alt text Missing alt text
A link with nothing a screen reader can read out Missing link text
A <button> with nothing a screen reader can read out Missing button text
An <iframe> with no title Missing iframe title
An <input>, <select> or <textarea> with no label Missing label
No <title>, or an empty one Missing title

Each is shown once, at the line in the template or the content that wrote it. A page with no template is published as its content alone, with no <title>, so it’s never noted for missing one.

Once every page is built, Statac reads the links on every page the way a browser would. What each link must lead to depends on where it points.

A link to Must lead to
A URL on the site A page, a feed, a file from assets/ or static/, a file in content/ beside a page, or an old URL that redirects. Otherwise it is a broken link.
#part of a page The id of a heading, a footnote or an element in that page’s HTML. Otherwise it is a missing anchor.
Another site The build doesn’t check it, because a build fetches nothing. If statac.yaml has check_external_links: true, statac refresh asks the other site, and statac check then gives a broken external link for a broken one. See checking links to other sites.
A path in served_elsewhere Statac doesn’t check it, because something else publishes there.
A path in after_build_outputs Statac doesn’t check it, because the after_build hook makes it after Statac builds the pages.

A broken link or a missing anchor is a warning, not an error: the page is still published with the link as you wrote it. Each is shown once, at the line that holds the link.

A few more details:

  • A link to the site’s own host, or to a host in other_hosts, is checked as a link into the site.
  • Links inside an HTML file that’s published unchanged aren’t followed.
  • If the site’s url has a path, such as /blog/, a link that starts with / leads outside the site. Write it with @url(...) instead.

Colour

Messages are coloured in a terminal, but the colour says nothing the words don’t. When the output goes to a file or another program, it has no colour. To change that:

Set What it does
NO_COLOR, to anything Turns colour off everywhere.
CLICOLOR_FORCE=1 Turns colour on when Statac would leave it off, such as when output goes to a pager that shows colour.
TERM=dumb Turns colour off, because it means the terminal can’t show colour. CLICOLOR_FORCE still turns it on.
COLORTERM, to truecolor or 24bit Shows Statac’s own orange exactly, instead of the nearest of 256 colours.

Where next?

Something unclear or wrong? Open an issue.