Errors
Every error and warning code the packages raise, with what it means.
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:nameA 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 emailEach 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.
plugins:name
Two plugins are named “<name>”.
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.
plugins:cycle
Plugin “<name>” is part of an
aftercycle.
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.
plugins:missing
Add <name>() to this form’s plugins: plugin “<requirer>” 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.
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.
plugins:loop
Plugins kept answering each other’s writes for 10 rounds: <names>.
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.
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.
schema:defaults
No schema plugin for vendor “<vendor>”, 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.
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.
dirty:missing
This form called
changes(), but it has nodirty(), so nothing tracks what changed. Adddirty()from “@lunarhue/forms-core/plugins” toplugins.
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().
arrays:missing
This form changed the length or order of an array, but it has no
arrays(). Addarrays()from “@lunarhue/forms-core/plugins” toplugins.
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.
submit:unseen
A submit failed on errors at <where>, 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).
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:
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:
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.
field:unknown
No field is named “<name>”, 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.
form:definition
useForm takes a definition from forms.define.
useForm got something that define didn’t return. Pass the definition
forms.define(...) returned.
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.
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.
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.
id:server
a form was server rendered without an
id. React before 18 has nouseId, so the generated id can’t match on the client. PassidtouseForm.
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.
field:target
give a bound component a
nameor ahandle.
A bound component, such as form.TextField, got neither name nor
handle. Pass name, or a handle.
context:form
useFormContext() found no form. Render it inside the form’s
form.Form.
useFormContext() found no form above it.
context:forms
useFormContext(forms) found no form made from those forms. It skips forms of other
createFormscalls. Render it inside theform.Formof a form made from one of their definitions.
useFormContext(forms) found no form made from one of those forms’
definitions.
context:definition
useFormContext(definition) found no form made from that definition. It skips forms of other definitions. Render it inside the
form.Formof a form made bycreateForm(definition).
useFormContext(definition) found no form made from that definition.
Last updated