Is it possible to receive field errors from onSubmit failure responses?

[lnhrdt]

I've been exploring adopting TanStack Form in my application. In our architecture, all form validation is done on the server, through submission. If the request is valid, the request succeeds. If the request is invalid, it returns a response of field errors (one or more).

I haven't found a way to adapt this architecture to TanStack Form. Is there a way to parse the response from an onSubmit failure (either thrown error or rejected promise) and apply the result to field errors?

[fulopkovacs]

TL;DR Currently, field errors can be set only from the field's validators, but we're planning to change this in the upcoming weeks.

Form validation on the server can be achieved using the form's onSubmitAsync validator, but unfortunately, there's no way to set field-specific errors in it.

You can validate the fields on the server by sending a fetch request in the field's onSubmitAsync validator (more about field validators here). Here's an example of an "age" field that sends its value to the server for validation when the user submits the form and returns an error message if the user is below 13 (the form will be also invalid in this case).

<form.Field
  name="age"
  validators={{
    onSubmitAsync: async ({value}) => {
         const below13: boolean = await validateAgeOnServer(value)
         return below13 ? 'You must be 13 to make an account' : undefined,
      }
  }}
>{...}</form.Field>

That's just what's currently possible, but your question sparked a conversation between the maintainers and we decided to implement a way to set field-specific errors from the form's validators. We already agreed on the API, and I picked up the task. I'm planning to do it in the upcoming weeks, but it's probably a tricky one, so please bear with me! 😅 I'm planning to ship it before v1.

[crutchcorn]

@lnhrdt we generally want to discourage usage that looks like what you've outlined, as it doesn't look good and is hard to follow.

Instead, we suggest using a onSubmitAsync + the currently unreleased form -> field API mapping

That said, what you wrote is technically possible but YMMV and we generally will not provide support for said usage.

[crutchcorn]

@fulopkovacs hinted at an API we're introducing to solve this problem. Here's the draft PR that's being used to introduce a fix:

#656

The idea is that your onSubmit validator (or any other form validator) might look like this:

const form = useForm({
  defaultValues: {
    firstName: '',
    lastName: '',
  },
  validators: {
    onSubmit: ({ value }) => {
      const firstNameMissingError =
        value.firstName.length > 0 ? undefined : 'First name is required'
      const lastNameMissingError =
        value.lastName.length > 0 ? undefined : 'Last name is required'

      return {
        fields: {
          firstName: firstNameMissingError,
          lastName: lastNameMissingError,
        },
      }
    },
  },
})

Then the errors in the onSubmit (or other validator, async included) will be mapped to the field.state.meta.errors area.

This should make this kind of validation much easier to handle, since we handle it for you predominantly :)

[lnhrdt]

@lnhrdt we generally want to discourage usage that looks like what you've outlined, as it doesn't look good and is hard to follow.

Instead, we suggest using a onSubmitAsync + the currently unreleased form -> field API mapping

That said, what you wrote is technically possible but YMMV and we generally will not provide support for said usage.

Hey @crutchcorn! I appreciate your insight and I'm glad to hear there will probably be a way to adapt our architecture to your library's API. I'll keep an eye on #656.

But I'm also getting the sense that our application's combined form validation/submission architecture might be less conventional than we thought. So please let me just double check my understanding one more time to make sure we're understanding each other. My application does not have a distinct validation process on the client or server side–in our architecture a form's server API submit endpoint is the only way to get validation errors. In this scenario, you'd recommend calling the form's server submit endpoint as a validator in your library, rather than in the onSubmit, because it's easier to follow?

[crutchcorn]

Good question @lnhrdt! (And sincere thanks for the patient tone with us as we figure out how to communicate this)

So if we think about how onSubmit is structured internally the code looks something like:

• Run validators.onSubmit sync validation
• Run validators.onSubmit async validation
• Run onSubmit if both don't have errors

Because of this, the idea is that all errors should be passed through our validators and only the successful logic should be in onSubmit

To be clear; we can still use your server's validation using the new feature + onSubmitAsync to handle the error setting internally for you rather than having to do things manually

[lnhrdt]

That helps me understand! While it wasn't intuitive to me to "submit in a validator" I can understand the rationale now.

It still surprises me that there isn't a more first-class mechanism to handle various errors in onSubmit (for network errors, if nothing else) but understanding that choice in the API, we'll probably use onSubmit more as an "onSuccess" and move everything to a validator.

Thank you!

[denisorehovsky]

I'm facing a similar issue. Waiting for the release of the improvement :)

[d3vzr]

For those struggling with setting field-specific errors from onSubmit, here's a workaround using setFieldMeta:

onSubmit: async ({ value }) => {
if (someCondition) {
setFieldMeta("fieldName", (prev) => ({
...prev,
errorMap: {
onChange: "Your error message here",
},
}));
return;
}
// Rest of your submit logic
}

This method allows you to set custom error messages for specific fields when handling submission failures or server-side validation responses. It's not ideal, but it works as a temporary solution until an official API is implemented for this use case.

[Ali-Albaker]

Exactly what I was looking for

[fulopkovacs]

@Ali-Albaker and everyone else interested in this issue: now that #656 has been merged, we have an official API for setting field-level errors from the form's validators.

Here's the example in the docs.

This is how @d3vzr's workaround would look like using the official APIs:

validators: {
  // Note that this is the onSubmit validator
  onSubmit: async ({ value }) => {
    if (someCondition) {
       return {
         fields: {
           fieldName: "Your error message here",
         }
      }
    }
    return null
  }
}

You can read more about setting field-level errors in the form's validators in the docs: https://tanstack.com/form/latest/docs/framework/react/guides/validation#setting-field-level-errors-from-the-forms-validators