Diagnostic codes

Each error and warning yuanme reports has a code, such as link/broken. yuanme docs CODE prints its page.

asset

asset/ambiguous-url: A URL names both a project file, which yuanme processes and hashes, and a Static file, which it copies unchanged: /styles/site.css is both styles/site.css and static/styles/site.css.
asset/classic-script: A <script src> without type="module" names a project file.
asset/css-in-script: A Script imports a stylesheet.
asset/dependencies-not-installed: A Script or stylesheet imports a package, and the project has a package.json but no node_modules.
asset/invalid-css: A stylesheet can’t be bundled: it isn’t valid CSS or UTF-8, or it imports one file twice in ways that can’t be merged, such as under two different @layers.
asset/invalid-script: A Script can’t be bundled: it isn’t valid JavaScript or TypeScript, or isn’t UTF-8, or it imports a name the other module doesn’t export, or a <script type="module"> names a file that is no Script.
asset/jsx: A Script is a .jsx or .tsx file, or has JSX in it.
asset/not-found: A <link href> or <script src> in a Page, an @import or url() in a stylesheet, or an import in a Script names a path that is no file of the project, no Static file and no URL of the Site.
asset/scope-collision: Two Sidecar stylesheets have the same scope attribute, which yuanme makes from each one’s path, so each one’s styles would reach the other’s Template.
asset/script-warning: The bundler warns about a Script, or a package it imports, that works but is likely a mistake, such as calling eval or importing a name that is always undefined.
asset/tailwind-error: Tailwind can’t build a stylesheet that does @import "tailwindcss": the Tailwind CLI reports an error, such as an @apply of a utility that doesn’t exist or an @plugin it can’t find, or a stylesheet that another one imports, or a Sidecar, imports Tailwind.
asset/tool-unavailable: yuanme can’t get a Managed tool the Site needs, such as the Tailwind CLI for a stylesheet that imports Tailwind, or TypeScript’s tsc with [typescript] check = true.
asset/type-error: With [typescript] check = true, TypeScript’s tsc finds a type error in a Script, or in a file a Script imports.
asset/unmatched-selector: A selector in a Sidecar stylesheet can match no tag its own Template writes.

budget

budget/css: The CSS a Page loads is over its Site budget, budgets.css: its stylesheets and <style> elements, each in kB of Brotli at quality 11.
budget/fonts: The text fonts a Page loads are over their Site budget, budgets.fonts: every font file that a stylesheet the Page loads names in url(), or that the Page preloads, but the math font, in kB of Brotli at quality 11.
budget/html: A Page’s first-flight HTML is over its Site budget, budgets.html: the whole document in kB of Brotli at quality 11, but an Entry’s Page without its body, which the build report lists apart.
budget/js: The JS a Page runs as it loads is over its Site budget, budgets.js: its Scripts, the chunks they import and its inline <script>s, each in kB of Brotli at quality 11.
budget/math-font: The math font a Page that shows math loads is over its Site budget, budgets.math_font, in kB of Brotli at quality 11.
budget/requests: A Page makes more requests on its render path than its Site budget, budgets.requests, allows.
budget/unknown-page: An Acknowledged overage in [budgets.overages] names a URL that is no HTML Page of the Site, so it silences nothing.

config

config/deprecated: A key in Site config has been renamed.
config/engine-version: The project needs a different version of yuanme than the one running: yuanme = "X.Y" is the oldest compatible version, with Cargo’s caret meaning, so 1.2 accepts any 1.x from 1.2 on and 0.3 accepts only 0.3.x.
config/invalid-value: A value in Site config has the right type but means nothing to yuanme: a URL that isn’t absolute, a Route without its placeholder, an unknown field type, or a name that refers to nothing.
config/missing-key: Site config leaves out a key that has no default.
config/out-of-range: A number in Site config is outside the range its key allows.
config/syntax: yuanme.toml is not valid TOML, so nothing else in it can be read.
config/unknown-key: Site config has a key yuanme doesn’t know.
config/wrong-type: A key in Site config has a value of the wrong TOML type, such as a string where a number goes.

entry

entry/duplicate-data-file: Two Data files share a name, such as data/nav.toml and data/nav.yaml, so data.nav would be ambiguous.
entry/duplicate-key: A key appears twice in the same mapping of front matter or a Data file, or an Org keyword that sets a field is given twice.
entry/duplicate-slug: Two Entries in one Collection have the same Slug, so they would be written to the same URL.
entry/invalid-date: A date or datetime field can’t be read.
entry/invalid-slug: A slug: override isn’t a valid Slug.
entry/invalid-value: A field’s value has the right type but isn’t allowed: an enum value not in its list, a URL that isn’t absolute, or an item repeated in a unique list.
entry/missing-field: An Entry, or an object inside one, leaves out a field that is required: title, or a declared field with neither optional = true nor a default.
entry/out-of-range: A field’s value is outside the min and max its Collection declares: a string’s length in characters, or a number.
entry/output-collision: Two Routes, or a Route and a Static file, would write the same file of the Site.
entry/syntax: An Entry’s front matter, or a Data file, can’t be read: it isn’t valid YAML, TOML or JSON, its --- is never closed, or the file isn’t UTF-8.
entry/term-collision: Two different Terms of a Taxonomy end up with the same Slug, because a slugs override in yuanme.toml gives one the Slug of another.
entry/toml-front-matter: An Entry starts with +++ TOML front matter.
entry/unknown-key: Front matter, or a Data file with a schema, has a key its Collection or schema doesn’t declare, or an Org Entry has a keyword that is neither a field nor one of Org’s.
entry/unknown-language: A code block names a language that no grammar highlights, so it is shown as plain text.
entry/wrong-type: A field has a value of the wrong type, such as a number where text goes.

host

host/cache-rule: A [[host.headers]] rule changes Cache-Control where yuanme’s cache policy has to hold: on a hashed file in /assets/, which must stay immutable, or on a Page, which must revalidate with max-age=0, must-revalidate so that a deploy shows at once.
host/output-collision: A Static file has the name of a file the Host adapter writes, such as static/_headers with the cloudflare or netlify adapter.
host/over-limit: Site config has more header rules or redirects, or a longer line, than a host yuanme supports accepts.
host/redirect-conflict: A [[host.redirects]] rule redirects a URL the Site serves: a Page, a Static file, or a Page’s URL without its trailing /, which hosts already redirect.
host/unsupported: The Site’s host can’t do what the Site needs.
host/wrangler-mismatch: wrangler.jsonc doesn’t serve the Site the way the cloudflare adapter writes it: assets.directory must be the output directory, assets.html_handling must be “auto-trailing-slash”, the default, and assets.not_found_handling must be “404-page” for the Site’s 404 Page to be served.

image

image/invalid: An image can’t be processed: it isn’t an image yuanme reads, it is damaged, it is over 100 megapixels, or it is a Static file, which is copied as it is.
image/missing-alt: An image in an Entry’s body has no alt text, so a screen reader can only say that an image is there.
image/not-found: An image in an Entry’s body, an image field or image() names a path where no image is.
image/remote: image() is given a remote URL.
image/unoptimized: A Page loads a raster image over 50 KB as it is, at full size and in its own format: a Static file, an image a stylesheet’s url() or a <link> names, or an animated GIF, WebP or PNG.

internal

internal/panic: yuanme crashed while processing a file.

link

link/broken: A Page links to, or loads, a URL of the Site where nothing is: no Page, Static file or asset of the build.
link/redirected: A Page links to a URL of the Site that hosts answer with a redirect, which costs the visitor a round trip: a Page’s URL without its trailing / or with index.html on the end, a .html file, a [[host.redirects]] rule’s from, or the Site’s address with or without www..
link/unresolved: A link to another file or a fragment doesn’t lead anywhere in the Site: no Entry has that file as its source, or the page has no element with that id.

markdown

markdown/empty-directive: A ::: line opens a block directive with no name.
markdown/no-effect: Something in a Markdown body is valid but changes nothing in the output, such as a [title] on a directive that isn’t a Theorem block.
markdown/out-of-fuel: A Markdown body would take longer to parse than yuanme allows for its length, so the build stops instead of hanging.

math

math/duplicate-label: Two things in one Entry have the same Label.
math/invalid-label: A Label has a character other than letters, digits, :, _, . and -.
math/named-environment: An Org LaTeX environment has a #+NAME.
math/tex-delimiter: A Markdown paragraph has \(…\), \[…\] or a bare \begin{…}, which Markdown doesn’t read as math: there \( and \[ are escaped brackets, as on GitHub and in Pandoc.
math/unknown-label: An \eqref, or an Org \ref, names a Label that no numbered equation in the Entry has.
math/unsupported: Math uses LaTeX that yuanme can’t render, or isn’t valid LaTeX: an unknown command or environment, a group that is never closed, or \label outside a numbered environment.

org

org/duplicate-id: Two Org Entries or headings have the same :ID: property, so an id: link to it could lead to either.
org/invalid-attribute: An #+ATTR_HTML line has text that isn’t an attribute.
org/misplaced-keyword: A keyword that sets one of the Entry’s fields, such as #+TITLE or #+DATE, comes after the first headline or body text.
org/no-effect: Something in an Org Entry is valid Org but changes nothing in yuanme’s output, such as a keyword for Org’s own exporter, an #+OPTIONS setting yuanme doesn’t do, or a #+CAPTION on a paragraph.
org/out-of-fuel: An Org paragraph would take longer to parse than yuanme allows for its length, so the build stops instead of hanging.
org/setupfile: An Org Entry has a #+SETUPFILE.
org/too-deep: Blocks, lists or markup in an Org body nest inside each other too deeply for yuanme to parse.
org/undefined-footnote: An Org footnote reference names a footnote that is never defined.
org/unknown-option: #+OPTIONS has an option Org doesn’t have, so it does nothing, in Emacs as in yuanme.
org/unsupported-construct: An Org body uses something outside the Org subset: macros, #+INCLUDE, #+CALL and other code that runs, citations, radio targets, dynamic blocks, inline tasks, headlines deeper than level 5, or a link type yuanme can’t follow.
org/wrong-weekday: An Org timestamp in a date field names a day of the week that isn’t the date’s.

template

template/bad-filter-argument: A filter or function got an argument it can’t use: a missing or unknown one, a value of the wrong type, a dateformat format it doesn’t know, or a - key passed to Jinja’s own sort, which reads it as a field name.
template/bad-header: A props comment on a Component, or a vars comment on a Layout, can’t be read or doesn’t match its macro: an entry that isn’t name: type or name?: type, an unknown type, a props comment that isn’t directly above a {% macro %}, a prop the macro doesn’t have or a parameter the comment doesn’t declare, or a macro in templates/components/ with no props comment.
template/bad-prop: A call to a Component passes a prop it doesn’t declare, leaves out one it requires, passes one of the wrong type or an optional value to a required prop, or gives a {% call %} body to a Component that takes none, or none to one that needs it.
template/bad-var: A Template extends a Layout without setting a variable its vars comment requires, or sets one to a value of the wrong type.
template/compare-optional: A Template compares an optional field with ==, !=, <, in or another comparison without a guard.
template/non-constant-name: extends, include or import names a Template with an expression.
template/not-found: A Template that a Route renders, or that another Template extends, includes or imports, is not in templates/.
template/render: A Template failed while rendering a Page: it printed a value that is absent, reached through one, or did something its values don’t allow.
template/syntax: A Template is not valid Jinja, so no Page that uses it can render.
template/undeclared-input: A Component reads a variable it wasn’t given: not one of its props, nor site, data, collections, taxonomies or page, which every Page sees.
template/unguarded-optional: A Template prints, loops over, filters or reaches through an optional field without a guard, so a Page whose Entry leaves it out fails to render.
template/unknown-block: A Template overrides a block that no Layout it extends has, so its content would never be shown.
template/unknown-field: A Template reads a field or a variable that isn’t in the schema of what its Page sees: a typo, a field of another Collection, a value only another kind of Route has, such as entries on a Taxonomy’s index, or a field of something that has none, such as a string.
template/unknown-filter: A Template calls a filter, test or function that neither Jinja nor yuanme has, a macro its import doesn’t define, or a method: Templates have no methods, such as Python’s .lower().
template/unknown-url: url() names a path that is no Route, feed or Static file of the Site, so the link would lead nowhere.
template/unscoped-tag: A Template with a Sidecar stylesheet writes a tag that yuanme can’t scope, or can’t check, as written.
template/wrong-type: A Template uses a value as a type it isn’t, such as looping over a string or passing a list to attrs.