SheetMillSheetMillTHE REFERENCE LIBRARY
← ALL REFERENCESEdit on GitHub

reference

Diagnostics

Every SheetMill diagnostic code, what it means, how to fix it, and how to check sheets in CI.

Every message has the form path:line:column: CODE: message on stderr. Errors stop the command with exit status 1 (invalid source) or 2 (usage or IO); warnings end with (warning) and do not change the exit status unless you use --strict with smill check or smill build navi.

Source and frontmatter

Source text

CodeMeaning and fix
SRC001Invalid UTF-8. Re-save the file as UTF-8 without a byte-order mark.
SRC002The file exceeds 8 MiB. Split it into several sheets.

Frontmatter

CodeMeaning and fix
FM001The file must start with a line containing exactly ---.
FM002The closing --- line is missing.
FM003The YAML is invalid or its root is not a mapping.
FM004A key appears twice in one mapping. Keep one.
FM005Anchors, aliases, merge keys, custom tags, non-finite numbers or nesting beyond 64 levels. Write plain JSON-compatible values.

Known fields

CodeMeaning and fix
VAL001title is missing or empty.
VAL002category or description is not a string, or tags is not an array of non-empty strings.
VAL003cheatsheet is not a mapping, cheatsheet.schema is not 1, cheatsheet.tool is empty, or navigation is not a mapping with only a non-blank string group and an integer order from 0 to 1000000.
VAL004cheatsheet.updated is not a real YYYY-MM-DD calendar date (years 1970 to 9999), or cheatsheet.tool_version is not one line of 1 to 64 characters without surrounding whitespace, control or invisible format characters, or either is not a quoted YAML string (an unquoted 3.81 is a number).

Structure and attributes

Sections and cards

CodeMeaning and fix
MD001A ### card appears before any ## section. Add a section heading above it.
MD002A section or card heading has no title text.
ID001Two headings use the same explicit #id, or an explicit ID collides with an earlier generated one. Rename one.

Heading attributes

CodeMeaning and fix
ATTR001Unsupported, malformed or misplaced token, for example {.unknown}, {.col-span-0} or {.cols-2} on a card. See the attribute table.
ATTR002The same setting is given twice, for example two .col-span- values.
ATTR003An attribute group outside a root ## or ### heading, such as a {.marker-none} line after a list. Remove it, or escape the brace (\{) to show it as text.

Website export

Errors

CodeMeaning and fix
REN001The renderer met content it cannot represent, or the project could not be assembled. Report it with the input.
REN002A link uses an unsafe or unsupported URL. Use relative, http, https or mailto links.
REN003Two inputs produce the same page route or basename, a route is reserved (assets, brand, tags; also studio in smill serve), --theme or --palette names an unknown value, no sheet is selected, or a base path, site URL, header link or GitHub base URL is invalid.

Warnings

CodeMeaning and fix
REN101Raw HTML is shown as inert text. Use Markdown instead.
REN102An image is kept as a link and never fetched.
REN103An internal link names no selected sheet, or its fragment matches no section or card ID. Fix the link, add an explicit {#id}, or pass --source-base-url for links to repository files.

navi export

Errors and warnings

CodeMeaning and fix
NAV000smill build navi --strict found warnings and wrote nothing. Fix them or drop --strict.
NAV001Unsupported --shell profile. Use bash, zsh, fish or nu.
NAV006Invalid or unknown cheatsheet.navi metadata, a reference to a missing/unmarked card or generated ID, a wrong shell, conflicting complete old/new parameter declarations, or an unusable tag.
NAV008Two exported entries share a pinned navi identity hash; navi would silently drop one.
NAV101–NAV106Warnings: a marked card was skipped (shape, command text, placeholder, declarations), the license is unstated, or a sheet exported nothing. NAV007 is retired (parameters are card-local); NAV107 is retired (frontmatter is preserved in the .navi.json companion). See navi export.

Input and output

Files and streams

CodeMeaning and fix
IO001An input cannot be read: missing, not a regular .md file, a symlink, or an empty directory selection.
IO002Writing to stdout failed, for example a closed pipe.
IO003The output exists already or cannot be created. Choose a new path; outputs are never overwritten.

Import

Reference import adds IMP001–IMP003 (errors) and IMP101–IMP112 (warnings about archived or mapped legacy syntax). See Reference import for the full list.

Checking in CI

Fail on every warning

--strict renders your sheets in memory, exactly as smill build hugo would, and turns every warning into an error. Nothing is written.

smill check --strict sheets

GitHub Actions

A minimal job that builds smill from a pinned SheetMill revision and checks the sheets in your repository. Replace the revision with the commit you trust.

name: sheets
on: [push, pull_request]
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          persist-credentials: false
      - uses: actions/setup-go@v6
        with:
          go-version: 1.27.2
      - run: go install github.com/wstein/sheetmill/cmd/smill@<revision>
      - run: smill check --strict sheets

Pin third-party actions to full commit SHAs in production workflows.

Shared command-card diagnostics

CodeMeaning
CMD001Invalid shared cheatsheet.cards mapping, card settings, parameter name/type/description or unknown key.
CMD002A .command card lacks an explicit ID, or shared metadata refers to a missing, unmarked or automatically identified card.

Source diagnostics point to the key/card; direct IR without key positions falls back to document start. Legacy-only selection/metadata keeps existing NAV behavior. Conflicting old/new complete declarations use NAV006; NAV008 collision behavior and pinned hashes are unchanged. See command cards and migration.

Studio preview diagnostics

CodeMeaning
STU001smill serve diagnoses selected input that is unavailable, unstable or oversized in the UI; see the CLI reference.