Skip to content
Source
Sign inSign up
TanStack/form

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

Mergedmomomuchu(GitHub profile, opens in a new tab)merged 3 commits intomain fromrefs/pull/2233/headmerged by crutchcorn(GitHub profile, opens in a new tab)

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.
    1. Review Change Stack

      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 6a73479f2c2659550a6c8b456e3e139bf0d2142e and f7e12e5a6ef3ab4d8af7e628379547bcd65f6095.

      📒 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

      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 nameStatusExplanation
      Title check✅ PassedThe title clearly summarizes the main fix for unmounted field errors in form-core.
      Description check✅ PassedThe PR description follows the template and includes the change, checklist, and release impact sections.
      Linked Issues check✅ PassedThe code and test changes address #2231 by defaulting missing meta and preventing the unmounted-field crash.
      Out of Scope Changes check✅ PassedThe changeset, fix, and test are all directly related to the reported crash and expected behavior.
      Docstring Coverage✅ PassedNo 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
      Comment `@coderabbitai help` to get the list of available commands.
    2. View your CI Pipeline Execution ↗ for commit 16e2f941ab79f98e5fd3499ef6654a9b428bc758

      CommandStatusDurationResult
      nx affected --targets=test:sherif,test:knip,tes...✅ Succeeded4m 36sView ↗
      nx run-many --target=build --exclude=examples/**✅ Succeeded40sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-07-09 09:41:58 UTC

    3. More templates

      @tanstack/angular-form

      npm i https://pkg.pr.new/@tanstack/angular-form@2233

      @tanstack/form-core

      npm i https://pkg.pr.new/@tanstack/form-core@2233

      @tanstack/form-devtools

      npm i https://pkg.pr.new/@tanstack/form-devtools@2233

      @tanstack/lit-form

      npm i https://pkg.pr.new/@tanstack/lit-form@2233

      @tanstack/preact-form

      npm i https://pkg.pr.new/@tanstack/preact-form@2233

      @tanstack/react-form

      npm i https://pkg.pr.new/@tanstack/react-form@2233

      @tanstack/react-form-devtools

      npm i https://pkg.pr.new/@tanstack/react-form-devtools@2233

      @tanstack/react-form-nextjs

      npm i https://pkg.pr.new/@tanstack/react-form-nextjs@2233

      @tanstack/react-form-remix

      npm i https://pkg.pr.new/@tanstack/react-form-remix@2233

      @tanstack/react-form-start

      npm i https://pkg.pr.new/@tanstack/react-form-start@2233

      @tanstack/solid-form

      npm i https://pkg.pr.new/@tanstack/solid-form@2233

      @tanstack/solid-form-devtools

      npm i https://pkg.pr.new/@tanstack/solid-form-devtools@2233

      @tanstack/svelte-form

      npm i https://pkg.pr.new/@tanstack/svelte-form@2233

      @tanstack/vue-form

      npm i https://pkg.pr.new/@tanstack/vue-form@2233

      commit: 16e2f94

    4. :warning: Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

      Codecov Report

      :white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 89.71%. Comparing base (6892ed0) to head (16e2f94). :warning: Report is 238 commits behind head on main. :exclamation: Your organization needs to install the Codecov GitHub app to enable full functionality.

      Additional details and impacted files
      @@            Coverage Diff             @@
      ##             main    #2233      +/-   ##
      ==========================================
      - Coverage   90.35%   89.71%   -0.64%     
      ==========================================
        Files          38       65      +27     
        Lines        1752     3200    +1448     
        Branches      444      806     +362     
      ==========================================
      + Hits         1583     2871    +1288     
      - Misses        149      295     +146     
      - Partials       20       34      +14     

      :umbrella: View full report in Codecov by Harness. :loudspeaker: Have feedback on the report? Share it here.

      :rocket: New features to boost your workflow:

      • :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
      • :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
  • Sign in to join this conversation.