Diagnostics

wf build, wf check, wf serve and your editor report the same findings, from one pipeline. Each starts with its code and what is wrong, then the place in the file:line:col form editors and CI read, the line of source with the part that is wrong underlined, what to do about it, and a link to its entry here:

• Errors stop the build: the program cannot mean what it says.
• Warnings print and the build goes on: it means something, probably not what you wanted. Nothing is a warning that the compiler could have decided for itself.

Every stage runs whatever the one before it found, and every file is read even when another does not parse, so one build shows every mistake once — then one line sums them up: error: the build stopped: 2 errors, 5 warnings. A build that stops on its findings exits with 1; one that could not run at all — a file it could not read, a config it could not load — with 2.

wf check --format json, sarif or github writes the same findings for a tool (Command line), and wf explain T05 prints a code's entry below in the terminal.

Fixes. Where the compiler knows the fix, it says so as edits, which your editor offers as a quick fix and --format json carries: the nearest name for a misspelled field, member, method, variable, component or flag (T05, T06, T16, T13, E101, E103), ?. for a read of a value that may be null (T04), the missing props with a value of their type (C01), the missing arms of a match (T15), a bare word written as the flag it means (V01), alt: "" for an image (A01), and an _ before a name nothing reads (U01–U05).

Allowing one finding. A // wf-allow(CODE) comment accepts a finding on purpose: on a line of its own it covers the next line of code, at the end of a line that line. It names codes or families, comma-separated — // wf-allow(U01, A). Only what lints could lower may be allowed, and an allow that covers nothing is itself reported (U07), so allows do not outlive what they were for. lints says the same for a whole project.

The code — T05 — is the thing to search this page for. The families:

Every example below is compiled by the test suite, draws exactly the code it is filed under, and shows what the compiler prints for it.

Errors, except where an entry says otherwise.

Fix: Close the string, comment or splice the message names. A character that begins nothing (| alone, a stray @) is usually a typo for the one beside it on the keyboard.

Fix: The message names what was expected and what was found, at the place the parser stopped. One file can report several: after an error the parser picks up again at the next declaration.

In a .wfx file, a line that comes back out to an indentation no enclosing block has:

Fix: Line the line up with the block it belongs to.

Fix: Run wf migrate once; it rewrites the project in place.

wf fmt checks that its result has the same tokens as the file. When it would not — something only the formatter's reading of the file would change — the file is left as it is and named. Fix: format the lines it names by hand; please report the file, since it is a bug in wf fmt.

Fix: Check the spelling, or declare it with component Buton { … }.

Fix: Rename one of the two. The finding points at the second and names where the first is.

Fix: Use one the message lists — it names every flag, case, event or slot the component takes.

Fix: Add slot to the component and place children where the page belongs.

Fix: Put it in on click { }, an action or an effect.

Fix: Button("Save") { on click { save() } }.

Fix: A relative URL, or http, https, mailto, tel, sms, ftp.

env.STRIPE_SECRET read in a page: env.STRIPE_SECRET is not public, and a page reads what is in the bundle. Fix: rename it PUBLIC_… or list it in public_env — only if anyone may read it (chapter 30).

A Button, an Input, a handler or a Router in a project whose output_type is pdf or slides. Fix: draw it as text, or build the page as a site.

A .js file under src/ with an import or export, one a file in public/ at the same address would replace, or one declaring a name the program, the language or the browser already has. Fix: take off the import/export (a top-level function is global as it is), keep one of the two files, or rename the clashing name.

A meta.scripts module with no as, a build.elements naming a component that does not exist, an offline.fallback no page has, an openapi.json that is not there. Fix: what the message says; it names the setting.

Warning. A key in webfluent.app.json that is not a setting, with the nearest one that is: ` build.minfy is not a setting, and nothing reads it — did you mean minify? ` Fix: correct the key.

Fix: Name the others: Card("Laptop", price: 999).

Fix: Fire the event from the component that declares it; a page calls an action instead.

Warning. A .js file under src/ the compiler's scanner could not read — a string that never closes, say. The file is still linked, but its names are not in scope for the program. Fix: what the message says, at the line it names.

Fix: A custom element's tag is lower case with a hyphen: Element("pricing-table").

The build reads back every script it writes; this one would not run. It is a bug in WebFluent, not in your program. Fix: please report it, with the source that produced it.

The build holds every page it writes to the content security policy it ships beside it; something on this page — an inline script, a style=, a script from an origin the policy never named — would be blocked. A page's own head { script(src: …) } or head { link(rel: "stylesheet", href: …) } is held to it too, where it is written: the tag is added on the live page, and the browser would refuse it there without a word. Fix: what the message says; a library's origin goes in meta.scripts, a stylesheet's in meta.stylesheets.

Fix: Modifiers ctrl, shift, alt, meta (or cmd), then one key: a letter, a digit, or a name — Enter, Escape, ArrowDown, Tab, F2.

Fix: Give it, or declare a default in the type (id: String = "") or on the prop.

Fix: Correct the spelling, or declare the prop on the component.

Fix: Place the part inside its owner: Select(bind: plan) { Select.Option(…) }.

Warning.

Fix: Check the prop's spelling — wf registry lists what the built-in takes. aria-*, data-* and the global attributes (id, role, title, …) are expected and draw nothing.

Warning.

Fix: Name it, with one of the props the built-in takes.

Warning.

Fix: Mark the prop the call means: component Tag2(_ label: String).

Fix: Hold what changes in a state. A derived value changes when what it reads does; a prop is its caller's (emit an event so the caller changes it); a route parameter is the address's (navigate); a loop variable is one pass's copy (change the item through its list).

Fix: Work a value out with derived; change state from the action or handler that changes what it depends on.

Fix: Call the action from a handler; derive from the state it sets.

Fix: Name a store that exists — here Cart.

Fix: Bind the state the reader edits (bind: first); show a value that is worked out with value:.

Fix: A number field is Input(…).number; a text field holds a String.

Fix: Bind the state to the control the reader fills in: Input(bind: email, label: "Email").email.

Warning.

Fix: Checkbox(bind: agree, label: "I agree").

Warning.

Fix: Start the state as one of the options' values.

Fix: Link to a route a page has; the message names the nearest. A spliced link is checked by its shape — "/team/{t.slug}" must match a route like /team/:slug — a link with no leading / is refused (where it leads would depend on the page it is on), and a link to a file (/report.pdf) or another site is left alone.

Fix: Declare the parameter the route names — page Profile(path: "/u/:id", id: String) — and read it by name; a declared parameter the route has no :name for is never filled.

Fix: Place Router where the page belongs: app { Navbar { … } Router }. (A program with no app at all routes its pages by itself.)

Warning.

Fix: Write it from the site's root: "/images/cover.png".

Warning. Image(src: "/img/hero.png") when public/img/hero.png does not exist (also poster:, captions:, transcript:): the page asks for it and gets a 404. Fix: put the file in public/, or correct the path.

Fix: Keep what it is made from — a name, an id, the data — and build the rest when it is read.

Warning.

Fix: Give each instance its own key: persist open = false { key: title }, with a prop that tells them apart.

Warning. The build remembers what each persist held (in .wf-cache/persist.json); when that changes — persist items = [] becomes persist items = { open: [], done: [] } — and version: does not, a returning reader's browser hands the old shape to code written for the new one. Fix: raise version: and add migrate 1 -> 2 { … } to bring the old value forward.

Warning. A font, stylesheet or script in meta.fonts, meta.stylesheets or meta.scripts from another origin, with no hash in meta.integrity. Fix: add its sha384-… hash to meta.integrity (the CDN usually publishes it). Google Fonts is exempt: its stylesheet differs per browser.

Errors. The type checker's findings; a program that declares no types raises none of them, since what it cannot resolve is Any.

Fix: Give the state a value of its type, or convert: Number(text), "{n}". If the state really holds either, declare it Any.

Fix: Use one of the cases the message lists, or add the case to the enum.

Fix: Unwrap it: if let e = user.email { e.toUpperCase() }, user.email?.toUpperCase(), or (user.email ?? "").toUpperCase().

Fix: Correct the spelling to one of the fields listed, or add the field to the type.

Fix: Use a member the store declares, or declare it: derived count = items.length. For a service, the endpoint must be declared in its api.

Fix: Ask the question you mean: items.length > 0, user != null.

Fix: Loop over a list — for n in 1..=total for a range of numbers.

Fix: Pass what the event declares, in order, or change the declaration.

Fix: Pass the arguments the action, endpoint or function takes.

Fix: Use if for a condition; match takes a resource, a connection or an enum.

Fix: Do not show, splice, log or persist a Secret. Send it in a request — or keep it on the server.

Fix: Correct the spelling, or declare the name. The browser's own globals (window, navigator, Math …) and the language's values (viewport, query, now …) need no declaration; a call to a function nothing declares — uid() for uuid() — is reported the same way. A template rendered with data (wf render) reads its data's keys by name, so it is not held to this.

Fix: Compare values of one type: count == 0, or convert one side (Number(text) == n). Against an enum, use a case it has.

Fix: Give every case its arm, or add else { … } for the rest. A match expression that covers every case needs no else: derived label = match status { .draft { "Draft" } .review { "In review" } .live { "Live" } }.

Fix: The method the message suggests — here join.

Fix: .pending is for an action that awaits — drop it here. An async action's result is read with await inside an action or a handler; a value that arrives over the network is a resource, which derived values and elements can read.

Fix: Hold numbers as numbers (state price = 12), or convert: Number(price) * 2.

Warning.

Fix: Say what to show instead: {user.nickname ?? "nothing yet"}, or show the line only when there is one: if let n = user.nickname { … }.

Warning.

Fix: error(e) { Alert(e.message).danger }, or an else.

Warning.

Fix: {tags.join(", ")} for a list of text; a field of a record.

These need the project's translation files, so the examples are described rather than run.

t("nav.blgo") when no locale's file holds nav.blgo: the page shows nav.blgo. Fix: the key the message suggests, or add it to the files.

t("greeting", { nme: user.name }) against "greeting": "Hello, {name}!": nme is not used, and {name} shows as written. Fix: pass what the message shows, by the name it shows it.

Warning. nav.blog in en.json and not in ar.json: a reader in Arabic sees nav.blog. Fix: translate it, or remove it from the others.

setLocale("fr") when i18n.locales is ["en", "ar"]. Fix: add the locale and its file, or name one that exists.

Warnings. What makes a page unusable with a screen reader, a keyboard or a voice.

Fix: Image(src: "/team.jpg", alt: "The team at the launch"). A purely decorative image takes alt: "".

Fix: IconButton(icon: "close", label: "Close") — the label is read aloud, never shown.

Fix: Input(bind: name, label: "Name"). A placeholder alone disappears as the reader types.

Fix: Checkbox(bind: agree, label: "I agree to the terms").

Fix: Give it text, or an aria-label: when it shows only an icon.

Fix: Give it text that names where it goes — not "click here".

Fix: Give the heading text, or remove it; style text with style { } rather than an empty heading.

Fix: Modal(visible: open, title: "Delete this?") — the title is its accessible name.

Fix: Video(src: …, captions: "/demo.en.vtt").controls; an Audio takes transcript:.

Fix: Put the first row in Table.Head, so its cells are <th scope="col">.

Fix: Use the next level down (h2 after h1). Size text with style { font-size }, not with the heading level.

Fix: One Heading(…).h1 per page, naming what the page is. A layout's h1 counts for the page it frames.

Fix: Darken the text or lighten the background until the ratio clears 4.5:1 (3:1 for large text).

Fix: Give each child the role the parent requires (role: "tab"), or use the built-in that owns the structure — Tabs.

Fix: Start the aria-label with the visible words: aria-label: "Save the draft".

Warning.

Fix: Make it unique — id: "row-{r}" — or drop it.

Warnings. What a search engine or a link preview would act on.

Fix: page P(path: "/", title: "What this page is").

Fix: Add a description: of about 150 characters: what a reader gets from the page.

Fix: Shorten it to about 160 characters.

Fix: Give each page its own path:. Only one of them would ever render.

Warnings. persist values across releases.

Fix: Add a step for each older version: migrate 1 -> 2 { old.map(…) }.

Fix: Raise version: to the step's target, or drop the step.

Fix: Keep route-scoped data in state, or move the value to a store with a wider scope.

Warnings. A name beginning _ is taken as unused on purpose.

Fix: Remove it, read it, or name it _unused to keep it on purpose.

Fix: Remove it or read it; a leading _ keeps it.

Fix: Place it, name it as a layout:, publish it in build.elements, or remove it.

Fix: Remove the member, or name it with a leading _.

Fix: Call it, remove it, or name it _reset.

Fix: Remove it, or move it above the return.

A // wf-allow(CODE) comment accepts one finding on purpose: on a line of its own it covers the next line of code, and at the end of a line it covers that line. It names codes (U01) or families (U), comma-separated, and only what lints could lower — a warning, or an error that ships no broken page. An allow that covers nothing it names is reported, so allows cannot outlive what they were written for.

Fix: Remove the allow — what it was written for is gone.

Fix: Use the value that decides, or remove the branch that cannot run.

Warning.

Fix: Key it: for r in rows by r.id.

Fix: Remove the else.

Warnings.

Fix: Write the flag with its dot — Button("Save").primary — or declare the name. The word is also a name nothing declares, so the build stops on it as T13; the editor shows both.

Fix: Wrap markup from outside the project in sanitize(…): Unsafe.Html(sanitize(body)).

A flag on one of your components whose class no stylesheet — the engine's or one of the project's .css files — defines, so it changes nothing on screen. The built-ins cannot draw it: the registry and the engine's stylesheet are held to each other. Fix: define the class in a .css file under src/, or drop the flag.

Fix: Name a class of your own and style it in a .css file under src/, or use the flag that sets the look you wanted (.primary, .elevated).

Warning.

Fix: The property the message suggests — here color. A custom property is written --name.

Fix: A token the theme has — a short name resolves through the property (padding: $lg, border: 1px solid $border) — or declare it in your theme { … }.

Warning.

Fix: Give it a unit: width: {pct}%.

Fix: Use one of the built-in icons the message lists.

Fix: Name a DOM event (click, input, change, submit, keydown, …) or one the component declares.

A Host is made of one of a few elements: div, span, canvas, svg, section, figure, pre, p, ul or table — the tag is written into the document, so it is an allow-list rather than whatever the string says. Any other tag is a div.

Fix: Make it one of the tags Host makes, or use the element the built-ins offer for it (Video, Audio, Image).

A call of a built-in's name draws the built-in, so a component declared with that name is never drawn: its body, its props, its slots go unused, and what the page shows is the built-in instead. It happens to a component written before WebFluent gained an element of the same name — a Footer from WebFluent 2, a Chart from before 5.2.

Fix: Rename the component and its call sites.