Skip to content
forms

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: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.

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 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.

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 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().

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.

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 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.

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.

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 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.

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.

Last updated