fix: flatten errors consistently when validating before field mount

Author: Kyujenius

.changeset/fix-nested-errors-on-manual-validate.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/form-core': patch
+'@tanstack/react-form': patch
+'@tanstack/angular-form': patch
+'@tanstack/vue-form': patch
+'@tanstack/solid-form': patch
+---
+
+fix: flatten errors consistently when validating before field mount
+
+Fixed an issue where `field.errors` was incorrectly nested as `[[error]]` instead of `[error]` when `form.validate()` was called manually before a field was mounted. The `flat(1)` operation is now applied by default unless `disableErrorFlat` is explicitly set to true, ensuring consistent error structure regardless of when validation occurs.

packages/form-core/src/FormApi.ts

@@ -1083,7 +1083,7 @@ export class FormApi<
             // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             const fieldInstance = this.getFieldInfo(fieldName)?.instance
 
-            if (fieldInstance && !fieldInstance.options.disableErrorFlat) {
+            if (!fieldInstance || !fieldInstance.options.disableErrorFlat) {
               fieldErrors = fieldErrors.flat(1)
             }
           }

packages/form-core/tests/FieldApi.spec.ts

@@ -2638,6 +2638,81 @@ describe('field api', () => {
       expect(field3.state.meta.errors).toContain('Field 3 error')
       vi.useRealTimers()
     })
+
+    it('should flatten errors when manually calling form.validate() before field mount', async () => {
+      vi.useFakeTimers()
+      const form = new FormApi({
+        defaultValues: {
+          name: '',
+        },
+        validators: {
+          onChange: ({ value }) => {
+            if (!value.name) {
+              return {
+                fields: {
+                  name: 'Name is required',
+                },
+              }
+            }
+            return undefined
+          },
+        },
+      })
+
+      form.mount()
+
+      // Manually validate BEFORE field mount
+      await form.validate('change')
+
+      // Now mount the field
+      const field = new FieldApi({ form, name: 'name' })
+      field.mount()
+
+      // Errors should be flattened [error], not [[error]]
+      expect(field.state.meta.errors).toEqual(['Name is required'])
+
+      vi.useRealTimers()
+    })
+
+    it('should respect disableErrorFlat option for mounted fields', async () => {
+      vi.useFakeTimers()
+      const form = new FormApi({
+        defaultValues: {
+          name: '',
+        },
+        validators: {
+          onChange: ({ value }) => {
+            if (!value.name) {
+              return {
+                fields: {
+                  name: [['Error level 1', 'Error level 2']],
+                },
+              }
+            }
+            return undefined
+          },
+        },
+      })
+
+      form.mount()
+
+      // Mount field with disableErrorFlat: true FIRST
+      const field = new FieldApi({
+        form,
+        name: 'name',
+        disableErrorFlat: true,
+      })
+      field.mount()
+
+      // Trigger validation after mount
+      field.setValue('')
+      await vi.advanceTimersByTimeAsync(50)
+
+      // Errors should NOT be flattened when disableErrorFlat is true
+      expect(field.state.meta.errors).toEqual([[['Error level 1', 'Error level 2']]])
+
+      vi.useRealTimers()
+    })
   })
 
   describe('deleteField functionality', () => {