fix(form-core): create complete field meta in setFieldValue for unmounted fields

[maricastroc]

🎯 Changes

form.setFieldValue() on a field with no mounted FieldApi created incomplete metadata. The setFieldMeta updater received undefined and spread it, which left the new entry without errorSourceMap, isBlurred, isValidating and the other default keys. A later FormGroup validator that reported an error for that field then hit fieldMeta?.errorSourceMap[errorMapKey] in distributeFieldErrors and threw TypeError: Cannot read properties of undefined (reading 'onChange'), aborting the handleChange that triggered validation.

The fix defaults the updater parameter to defaultFieldMeta ((prev = defaultFieldMeta) =>), the same pattern used by the form-level error fan-out in FormApi and by #2233 in FormGroupApi. It fixes the inconsistent metadata where it is created instead of guarding the reader. Existing metadata for mounted fields is unchanged.

Regression tests cover:

• the reproduction from the issue: handleChange no longer throws, the group error is assigned to the unmounted field with source form, it surfaces when the field mounts and clears once the value is fixed
• setFieldValue on an unmounted field creating complete metadata
• setFieldValue preserving existing metadata (isBlurred, other errorMap keys, errorSourceMap) on a mounted field

Closes #2432

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested code changes locally with pnpm test:pr, or these tests do not apply to this pull request.
• I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Bug Fixes
  • Fixed errors when group validation targets a field that was updated before it was mounted.
  • Ensured field metadata is initialized and existing validation and interaction state is preserved when field values change.

[changeset-bot]

🦋 Changeset detected

Latest commit: 76b33dc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 14 packages

Name	Type
@tanstack/form-core	Patch
@tanstack/angular-form	Patch
@tanstack/form-devtools	Patch
@tanstack/lit-form	Patch
@tanstack/preact-form	Patch
@tanstack/react-form	Patch
@tanstack/solid-form	Patch
@tanstack/svelte-form	Patch
@tanstack/vue-form	Patch
@tanstack/react-form-devtools	Patch
@tanstack/solid-form-devtools	Patch
@tanstack/react-form-nextjs	Patch
@tanstack/react-form-remix	Patch
@tanstack/react-form-start	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: TanStack/form/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3a8913d8-6746-4dcf-8e75-873c43d9fd57

📥 Commits

Reviewing files that changed from the base of the PR and between 2216fde and 76b33dc.

📒 Files selected for processing: 4

• .changeset/complete-unmounted-field-meta.md
• packages/form-core/src/FormApi.ts
• packages/form-core/tests/FormApi.spec.ts
• packages/form-core/tests/FormGroupApi.spec.ts

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📝 Walkthrough

setFieldValue now initializes metadata for an unmounted field with defaultFieldMeta. Tests cover metadata creation and preservation, plus group validation errors for a field without a mounted FieldApi.

Changes: Unmounted Field Metadata

Layer / File(s)	Summary
Initialize metadata and verify group validation packages/form-core/src/FormApi.ts, packages/form-core/tests/FormApi.spec.ts, packages/form-core/tests/FormGroupApi.spec.ts, .changeset/complete-unmounted-field-meta.md	setFieldValue now defaults missing metadata to defaultFieldMeta. Tests check metadata defaults, preservation of existing state, and group validation errors for an unmounted field. A patch changeset records the fix.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 76b33

No actionable issue is identified for this change; it is mergeable after normal checks.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly and concisely describes the primary change: creating complete field metadata in setFieldValue for unmounted fields.
Description check		The description includes the required Changes, Checklist, and Release Impact sections. It explains the motivation, implementation, regression tests, issue reference, test status, and changeset status.
Linked Issues check		Issue #2432 requires setFieldValue() on an unmounted field to avoid the FormGroup live-validation exception and to assign the group error to that field. The PR defaults the metadata updater to `defa…
Out of Scope Changes check		The changed production code directly fixes the incomplete metadata described by #2432. The added tests verify the reproduction and metadata behavior. The changeset documents the published bug fix. No …
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3…

Full details: Linked Issues check

Explanation

Issue #2432 requires setFieldValue() on an unmounted field to avoid the FormGroup live-validation exception and to assign the group error to that field. The PR defaults the metadata updater to defaultFieldMeta. The reported regression test covers successful handleChange, error assignment with source form, error visibility after mounting, and error clearing after a valid value. Additional tests cover complete metadata creation and preservation of existing metadata.

Full details: Out of Scope Changes check

Explanation

The changed production code directly fixes the incomplete metadata described by #2432. The added tests verify the reproduction and metadata behavior. The changeset documents the published bug fix. No unrelated changes are identified in the supplied PR evidence.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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