# Errors

> Every error and warning code the packages raise, with what it means.

Source: https://forms.lunarhue.dev/errors

Every error and warning the packages raise has a code, written `area:name`.
In development the message is a sentence that says what went wrong,
followed by a link to the code's entry on this page:

```
@lunarhue/forms-core: Two plugins are named "email". https://forms.lunarhue.dev/errors#core:plugins:name
```

A production build drops the sentence and the link to save bytes and keeps
the code. When a sentence names something, such as a plugin, the name comes
after the code:

```
@lunarhue/forms-react: context:form
@lunarhue/forms-core: plugins:name email
```

Each entry below has the sentence, with the named value in angle brackets,
so a production message can be read back from its code. The anchor of an
entry is the package and the code, as in `#react:context:form`.

Each package keeps the address in one constant, `docs` in its
`src/problem.ts`.

The Vue adapter, `@lunarhue/forms-schema` and `@lunarhue/forms-bind` raise
no errors of their own.

## Core

These come from `@lunarhue/forms-core`. The adapters use core, so a React,
Solid or Vue app gets them too.

`onPluginError` is an option of `createForms`. Without it, an error sent
there is thrown on a later task, so it reaches the page's error handler
without breaking the write that was running.

<a id="core:plugins:name"></a>

### `plugins:name`

> Two plugins are named "&lt;name&gt;".

Thrown when the store is made. Two hook plugins in one store have the same
name. The lists on `createForms`, on the definition and on the form all
count. Install the plugin once. To run two masks side by side, give one a
`name`. A form has one `bind`.

<a id="core:plugins:cycle"></a>

### `plugins:cycle`

> Plugin "&lt;name&gt;" is part of an `after` cycle.

Thrown when the store is made. The plugins' `after` lists make a loop, such
as `a` after `b` and `b` after `a`. Remove a name from one of the `after`
lists.

<a id="core:plugins:missing"></a>

### `plugins:missing`

> Add &lt;name&gt;() to this form's plugins: plugin "&lt;requirer&gt;" requires it.

Thrown when the store is made, or when a field type or fieldset attaches
its parts. A plugin's `requires` names a plugin the form doesn't have, or
a part, such as `masked(...)` on a field type, needs a plugin the form
doesn't have. The types report this too, so it shows up where the types
don't reach, such as a `define` call with a cast. It is development only:
a production build skips the check, and a part with no plugin does nothing.
Add the plugin to the form's `plugins` or to the definition's.

<a id="core:plugins:write"></a>

### `plugins:write`

> A plugin wrote to the store from inside a hook. Write through `ctx.write`.

Sent to `onPluginError`. A plugin wrote to the store directly while one of
its hooks was running, `setup` included. Write inside `ctx.write`. The write
then runs once every plugin in the round has run.

<a id="core:plugins:loop"></a>

### `plugins:loop`

> Plugins kept answering each other's writes for 10 rounds: &lt;names&gt;.

Sent to `onPluginError`. Plugins kept answering each other's writes for 10
rounds in one batch, and the writes still waiting are dropped. The value is
the names of the plugins still writing. Make a plugin skip writes it caused,
by checking `record.cause`, or write only when the value would change.

<a id="core:plugins:copies"></a>

### `plugins:copies`

> This store's plugins come from two copies of @lunarhue/forms-core. Install one copy.

A warning, logged in development only. The app bundles two copies of core,
and plugins only work with the copy they were made with. Install one copy,
as by deduping the lockfile.

<a id="core:schema:defaults"></a>

### `schema:defaults`

> No schema plugin for vendor "&lt;vendor&gt;", so the definition needs defaultValues.

Thrown when the store is made. The definition has a `schema` from a library
with no schema plugin installed, and no `defaultValues`. Install that
library's schema plugin, such as `valibot()` or `zod()`. For a library with
none, such as arktype, give complete `defaultValues`.

<a id="core:rebase:store"></a>

### `rebase:store`

> rebase: the handle belongs to another store.

Thrown by `form.plugins.rebase`, as a `TypeError`. The handle passed to
`rebase` belongs to another store. Pass a handle of the form the `rebase`
plugin is installed on.

<a id="core:dirty:missing"></a>

### `dirty:missing`

> This form called `changes()`, but it has no `dirty()`, so nothing tracks what changed. Add `dirty()` from "@lunarhue/forms-core/plugins" to `plugins`.

Thrown in development only. Something called `changes()` on a form whose
plugins have no `dirty()`. TypeScript already rejects that call, so this
reaches code without types or code that cast the store. Add `dirty()` from
`<adapter>/plugins` to `plugins`, on `createForms` or on the definition. In
production `changes()` returns an empty list.

Reading `dirty` on such a form is a type error too, but at runtime it gives
`false` and throws nothing. So when a Save button that waits for `dirty` never
enables, first check that the form has `dirty()`.

<a id="core:arrays:missing"></a>

### `arrays:missing`

> This form changed the length or order of an array, but it has no `arrays()`. Add `arrays()` from "@lunarhue/forms-core/plugins" to `plugins`.

Thrown in development only. Something called `push`, `insert`, `remove` or
`move` on an array of a form whose plugins have no `arrays()`. TypeScript
already rejects those calls, so this reaches code without types or code that
cast the handle. Add `arrays()` from `<adapter>/plugins` to `plugins`, on
`createForms` or on the definition. In production the commands do nothing.

`setValue` on the array still works without `arrays()`. The Arrays page
says how rows behave then.

<a id="core:submit:unseen"></a>

### `submit:unseen`

> A submit failed on errors at &lt;where&gt;, and nothing on the page reads them, so the user sees no error. Render the form's root errors, and the errors of object and array fields.

A warning, logged in development only, once per store. A submit failed, and
the only errors are on the root or on an object or array field that nothing
reads. The user sees nothing, and focus goes to the `<form>`.

Every form should render its root errors. Errors land on the root in three
ways:

- The schema rejects the value as a whole, such as "Invalid type: Expected
  Object but received undefined", or a check across fields has no path.
- A server error comes back for the whole form, through `setErrors({ form })`.
- An error names a field that doesn't exist, so it falls back to the root
  (see [`field:unknown`](#core:field:unknown)).

Errors on an object or array field, such as an empty list that needs a row,
stay on that field. Render them next to its fields.

In React:

```tsx
const errors = useField(form.root, (snapshot) => snapshot.shownErrors);

<ul id={errorId(form.root)}>
  {errors.map((error) => (
    <li key={error.message}>{error.message}</li>
  ))}
</ul>;
```

In Solid:

```tsx
const root = createField(form.root);

<ul id={root.errorId}>
  <For each={root.shownErrors}>{(error) => <li>{error.message}</li>}</For>
</ul>;
```

Core can't see the page. It counts an error as read when something
subscribes to its field, as `useField` and `createField` do. The warning
stays quiet when any field with an error is read. It names only the root and
fields that have fields read under them, since an unread field may be on a
step the app shows after the submit. It can miss a case too. A component
that reads the root's value, or a list's items, counts as reading its errors.

<a id="core:field:unknown"></a>

### `field:unknown`

> No field is named "&lt;name&gt;", so its errors went to the form's root. Check the name, and render the root errors.

A warning, logged in development only, once per name per store. `setErrors`
or a form validator's `fields` used a name that matches no field, so its
errors were added to the root's, after the `form` errors.

A name matches a field when each step exists in the form's value: a key its
object has, or an index its array has. A key the value lacks still counts
when something renders or validates a field there, such as an optional
field with an input. Every name under a missing object counts too, since the
value can't say what that object would hold. A step into a string or other
leaf never counts.

The usual cause is a server that renamed a field, or a typo. Fix the name. To
route these errors yourself, check each name with `store.pathOf(name)`, which
returns `undefined` for the same names.

## React

These come from `@lunarhue/forms-react`.

<a id="react:form:definition"></a>

### `form:definition`

> useForm takes a definition from forms.define.

`useForm` got something that `define` didn't return. Pass the definition
`forms.define(...)` returned.

<a id="react:context:form"></a>

### `context:form`

> no form.Form is mounted above this component. Render it inside form.Form, or pass the form down as a prop.

`useFormContext()` found no form above it. Render the component inside
`form.Form`, or pass the form down as a prop.

<a id="react:context:forms"></a>

### `context:forms`

> no form.Form of these forms is mounted above this component. Forms of other createForms calls don't count. Render it inside the form.Form of a form made from one of their definitions.

`useFormContext(forms)` found no form made from one of those forms'
definitions.

<a id="react:context:definition"></a>

### `context:definition`

> no form.Form of this definition is mounted above this component. Forms of other definitions don't count. Render it inside the form.Form of a form made from it.

`useFormContext(definition)` found no form made from that definition.

<a id="react:id:server"></a>

### `id:server`

> a form was server rendered without an `id`. React before 18 has no `useId`, so the generated id can't match on the client. Pass `id` to `useForm`.

A warning, logged in development only. React 16.8 and 17 have no `useId`,
so the generated id can't match on the client. Pass `id` to `useForm`.

## Solid

These come from `@lunarhue/forms-solid`.

<a id="solid:field:target"></a>

### `field:target`

> give a bound component a `name` or a `handle`.

A bound component, such as `form.TextField`, got neither `name` nor
`handle`. Pass `name`, or a `handle`.

<a id="solid:context:form"></a>

### `context:form`

> useFormContext() found no form. Render it inside the form's `form.Form`.

`useFormContext()` found no form above it.

<a id="solid:context:forms"></a>

### `context:forms`

> useFormContext(forms) found no form made from those forms. It skips forms of other `createForms` calls. Render it inside the `form.Form` of a form made from one of their definitions.

`useFormContext(forms)` found no form made from one of those forms'
definitions.

<a id="solid:context:definition"></a>

### `context:definition`

> useFormContext(definition) found no form made from that definition. It skips forms of other definitions. Render it inside the `form.Form` of a form made by `createForm(definition)`.

`useFormContext(definition)` found no form made from that definition.
