fix(form-core): don't throw when a group validator errors an unmounted field

[momomuchu]

FormGroupApi.distributeFieldErrors throws TypeError: Cannot read properties of undefined (reading 'errorMap') when a FormGroup validator returns { fields } errors for a sub-field that is not mounted yet (no fieldMetaBase entry). This happens in multi-step forms where each step is a FormGroup and fields render progressively.

setFieldMeta's updater is invoked with prev.fieldMetaBase[field], which is undefined for a never-mounted field. The fix defaults the updater parameter to defaultFieldMeta ((prev = defaultFieldMeta) => ...), mirroring the same fix already applied in FormApi.ts for this bug class (#1706, #2056). The distributed error is stored and surfaces correctly when the field later mounts.

Added a FormGroupApi.spec.ts case: a group validator returns errors for an unmounted field, validate runs, and it must not throw. It throws the reported TypeError without the fix and passes with it. Full form-core suite (499 tests) and type tests pass, eslint and tsc clean.

Closes #2231

Summary by CodeRabbit

• Bug Fixes

  • Fixed an issue where form group validation could fail when errors were returned for a field that had not been mounted yet.
  • Error handling now works more reliably for fields that mount after validation, so previously hidden errors appear correctly once the field is available.

• Tests

  • Added coverage for mounting fields after group validation to ensure errors are distributed as expected.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 961478ce-ac3b-4554-b510-b480b6066c76

📥 Commits

Reviewing files that changed from the base of the PR and between 6a73479 and f7e12e5.

📒 Files selected for processing (3)

• .changeset/fix-formgroup-distribute-unmounted-field.md
• packages/form-core/src/FormGroupApi.ts
• packages/form-core/tests/FormGroupApi.spec.ts

---

📝 Walkthrough

Walkthrough

Fixes a TypeError in FormGroupApi.distributeFieldErrors that occurred when a group validator returned errors for a field not yet mounted, by defaulting the previous field meta to defaultFieldMeta. Adds a regression test and a changeset entry.

Changes

FormGroupApi Unmounted Field Fix

Layer / File(s)	Summary
Default field meta on distribution packages/form-core/src/FormGroupApi.ts	setFieldMeta updater in distributeFieldErrors now defaults prev to defaultFieldMeta when undefined, preventing a TypeError when merging errorMap/errorSourceMap for unmounted fields.
Regression test and changeset packages/form-core/tests/FormGroupApi.spec.ts, .changeset/fix-formgroup-distribute-unmounted-field.md	Adds a test confirming mount() does not throw when a group validator returns errors for an unmounted field and that the error surfaces once the field mounts; adds a changeset entry documenting the patch.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Validator
  participant FormGroupApi
  participant FormApi
  Validator->>FormGroupApi: return fields errors for unmounted field
  FormGroupApi->>FormApi: setFieldMeta(fullName, updater)
  FormApi->>FormGroupApi: updater(prev = undefined)
  FormGroupApi->>FormGroupApi: default prev to defaultFieldMeta
  FormGroupApi-->>FormApi: merged errorMap/errorSourceMap

Loading

Related issues: #2231 (FormGroup validator returning sub-field errors for unmounted fields throws "Cannot read properties of undefined (reading 'errorMap')")

Suggested labels: bug, form-core, patch

Suggested reviewers: none identified from provided context

🐰 A field not yet born, no meta to its name,
The validator scolds it just the same,
Now defaults step in, no more the crash,
Errors wait patiently till the field's next flash.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main fix for unmounted field errors in form-core.
Description check	✅ Passed	The PR description follows the template and includes the change, checklist, and release impact sections.
Linked Issues check	✅ Passed	The code and test changes address #2231 by defaulting missing meta and preventing the unmounted-field crash.
Out of Scope Changes check	✅ Passed	The changeset, fix, and test are all directly related to the reported crash and expected behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}