Support parent-level error display for deeply nested field values

[ap32]

Problem

Some fields are one field from the form/UI perspective, but their value is a nested structure.

Examples:

const Schema = v.object({
  // Tiptap / ProseMirror JSON
  content: TiptapContentSchema,

  // Editor.js output
  article: EditorJsOutputSchema,

  // Reka UI Tags Input or similar tag editor
  tags: v.array(TagSchema),

  // File upload field with per-file metadata
  files: v.array(FileWithMetadataSchema),
});

These are usually not separate form fields. They are one custom field connected with useField() or <Field>:

<Field :of="form" :path="['content']" v-slot="field">
  <TiptapEditor v-model="field.input" />

  <div v-if="field.errors?.[0]">
    {{ field.errors[0] }}
  </div>
</Field>

<Field :of="form" :path="['tags']" v-slot="field">
  <TagsInputRoot v-model="field.input">
    <!-- tags input implementation -->
  </TagsInputRoot>

  <div v-if="field.errors?.[0]">
    {{ field.errors[0] }}
  </div>
</Field>

<Field :of="form" :path="['files']" v-slot="field">
  <FileUploadField v-model="field.input" />

  <div v-if="field.errors?.[0]">
    {{ field.errors[0] }}
  </div>
</Field>

The problem is that validation can fail deeper inside the value:

content.content.0.content.1.text
article.blocks.3.data.items.0.content
tags.2.label
files.0.metadata.crop.width

But from the form perspective, the error often needs to be displayed at the parent field:

content
article
tags
files

The user does not interact with content.content.0.content.1.text as a separate field. They interact with one Tiptap editor.

The same applies to Editor.js, tags input, and upload fields with nested metadata.

Current limitation

Formisch already has getDeepErrors and getDeepErrorEntries, but for this use case the field usually only needs the first relevant deep error.

Using getDeepErrors(...)[0] is not ideal because it suggests collecting all descendant errors just to render one message.

The missing primitive is a way to ask:

What is the first error for this field, including errors below this field path?

For example:

getDeepError(form, { path: ['content'] })
getDeepError(form, { path: ['article'] })
getDeepError(form, { path: ['tags'] })
getDeepError(form, { path: ['files'] })

Expected behavior:

1. Check direct errors at the requested path.
2. Search descendant errors.
3. Return the first error.
4. Stop searching after the first match.

Then a field could be written like this:

<Field :of="form" :path="['content']" v-slot="field">
  <TiptapEditor v-model="field.input" />

  <div v-if="field.errors?.[0] || getDeepError(form, { path: ['content'] })">
    {{ field.errors?.[0] ?? getDeepError(form, { path: ['content'] }) }}
  </div>
</Field>

A related helper could also be useful:

getDeepErrorEntry(form, { path: ['content'] })

returning the original path together with the message:

{
  path: ['content', 'content', 0, 'content', 1, 'text'],
  error: 'Content is required'
}

Possible Valibot-level solution

This could also be solved at the schema level.

Valibot could provide a way to mark a schema as an error boundary / error surface:

const Schema = v.object({
  content: v.errorBoundary(TiptapContentSchema, {
    mode: 'first',
  }),

  article: v.errorBoundary(EditorJsOutputSchema, {
    mode: 'first',
  }),

  tags: v.errorBoundary(v.array(TagSchema), {
    mode: 'first',
  }),

  files: v.errorBoundary(v.array(FileWithMetadataSchema), {
    mode: 'first',
  }),
});

Then an issue at:

tags.2.label

could be surfaced as:

tags

For example, flattened errors could become:

{
  nested: {
    tags: ['Tag label is required']
  }
}

instead of only:

{
  nested: {
    'tags.2.label': ['Tag label is required']
  }
}

Possible behavior:

type ErrorBoundaryOptions = {
  mode?: 'first' | 'all' | number;
  message?: string | ((issues: BaseIssue[]) => string);
  preserveIssues?: boolean;
};

Examples:

v.errorBoundary(schema, { mode: 'first' })

Surface only the first deep issue at the parent path.

v.errorBoundary(schema, { mode: 'all' })

Surface all deep issue messages at the parent path.

v.errorBoundary(schema, { message: 'Invalid content' })

Use one parent-level message instead of exposing internal paths/messages.

Suggested direction

This could be solved in Formisch, Valibot, or both.

On the Formisch side, an optimized helper like this would solve the immediate UI problem:

getDeepError(form, { path })
getDeepErrorEntry(form, { path })

On the Valibot side, an error boundary / error surface would solve it semantically:

v.errorBoundary(schema, { mode: 'first' })

I think the Valibot-level solution is the cleaner long-term solution because the schema author knows whether a nested value should behave as one field.

The Formisch-level helper is still useful because field components often need a simple and performant way to display the first descendant error for a field.

[fabian-hiller]

Thank you for reporting this! For now, as a workaround calling getDeepErrors(...)[0] should be fine but yes, we should look into improving this. I could also imagine adding a new config prop to getDeepErrors and getDeepErrorEntries to only return the first error found.

@dosu what do you think about this issue? How would you improve it? What do you recommend?

[dosubot]

Great issue — this is a real UX gap for complex field components. Here's my take:

Recommended approach: Add a limit config option to the existing utilities

The cleanest Formisch-level improvement would be adding a limit (or count) option to the existing getDeepErrors and getDeepErrorEntries config, since both already use walkFieldStore to traverse the field tree [1] [2]. With early termination when limit is reached, this avoids the "collect everything, use one" inefficiency:

getDeepErrors(form, { path: ['content'], limit: 1 })
getDeepErrorEntries(form, { path: ['tags'], limit: 1 })

This keeps the API surface minimal (no new functions), is fully backward-compatible (limit defaults to Infinity), and the walkFieldStore callback could simply short-circuit once enough errors are collected.

Why I'd lean toward this over separate getDeepError / getDeepErrorEntry helpers:

• It avoids API proliferation — fewer functions for users to learn
• It's more flexible (e.g., limit: 3 for showing up to 3 errors in a summary)
• The naming stays consistent with the existing API

On the Valibot v.errorBoundary() idea:

I agree with the issue author that this is the semantically cleaner long-term solution — the schema author knows that content is one logical field. However, it's a bigger design surface (mode, message transformation, preserveIssues, how it interacts with flatten(), etc.), and it solves a slightly different problem (schema-level error aggregation vs. UI-level error display).

My recommendation:

1. Short-term (Formisch): Add limit: number to GetFieldDeepErrorsConfig and GetFieldDeepErrorEntriesConfig, with early exit in walkFieldStore. This solves the performance concern and the ergonomic "just give me the first error" use case immediately.

2. Long-term (Valibot): Explore v.errorBoundary() as a separate effort. It's valuable but orthogonal — it changes where errors are reported in the issue tree, whereas limit changes how many the consumer reads.

Both can coexist: even with v.errorBoundary(), a field component might still want limit: 1 to display only one message when multiple boundary-level errors exist.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[fabian-hiller]

Another option could be that useField and <Field /> return nested errors by default. It seems unlikely and is probably not recommended to use useField and <Field /> for an outer and inner field. A field should always be the final unit. Therefore it could make sense that useField and <Field /> return nested errors by default. What do you think?

[ap32]

I think this should be primarily solved at the schema level for performance reasons. In theory, developers may define higher-level validation errors (for example, for arrays, maybe some rawTransform errors), which could result in duplicate error messages being displayed.

While Field is generally recommended to be used only for fields, there can be valid exceptions, so I don't think Field should be restricted exclusively to fields. In some cases, it may also be appropriate for outer values.

[fabian-hiller]

I think this should be primarily solved at the schema level

Do you mean users should write the schema so that the errors are displayed and the correct field?

While Field is generally recommended to be used only for fields, there can be valid exceptions

Do you have an example for such an exception?

[ap32]

Yes, I think solving error collection at the schema level is more effective. The schema is the right place to define which complex values should act as error boundaries and where nested errors should be surfaced. It also keeps deep error collection explicit instead of making every Field traverse its descendants by default.

I also tried to find strong cases where Field really needs to represent a non-field value, but I could not find many. In most of those cases, Formisch already provides separate functions for retrieving the specific state or errors needed, so the UI can usually be implemented without treating the outer value as a Field.