traverseFields silently skips localized group/tab children when walking locale-resolved documents

[FinnIckler]

Describe the Bug

traverseFields accepts a document as ref and walks it against the field schema, which makes it the natural utility for anything that needs "every field value in this document, with its schema". But it assumes ref is in the database shape, where a localized field holds a map of locale → value. A document fetched through the public API (payload.find({ locale }), payload.findByID({ locale }), payload.findGlobal({ locale })) is in the resolved shape, where a localized field holds the value for that one locale.

For localized group and tab fields the code iterates for (const key in currentRef) treating each key as a locale, recurses with ref set to the value rather than an object of values, hits the if (!ref || typeof ref !== 'object') return check, and stops, which causes the entire subtree under the localized group is skipped.

Link to the code that reproduces this issue

https://stackblitz.com/edit/traverse-field-repro

Reproduction Steps

Run npm run repro

Actual output:

title (text)
legal (group)
links (array)
links.label (text)      ← the localized array works

Expected output: the same, plus legal.notice (text). It is the only field in the document
that is never visited, and nothing signals that it was skipped.

Which area(s) are affected?

area: core

Environment Info

Binaries:
  Node: 22.14.0
  npm: 10.9.2
  Yarn: 4.17.0
  pnpm: N/A
Relevant Packages:
  payload: 3.89.0
  next: 16.3.5
  @payloadcms/db-mongodb: 3.89.0
  @payloadcms/db-sqlite: 3.89.0
  @payloadcms/drizzle: 3.89.0
  @payloadcms/graphql: 3.89.0
  @payloadcms/live-preview: 3.89.0
  @payloadcms/live-preview-react: 3.89.0
  @payloadcms/next/utilities: 3.89.0
  @payloadcms/plugin-cloud-storage: 3.89.0
  @payloadcms/richtext-lexical: 3.89.0
  @payloadcms/storage-s3: 3.89.0
  @payloadcms/translations: 3.89.0
  @payloadcms/ui/shared: 3.89.0
  react: 19.3.0
  react-dom: 19.3.0
Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.6.0: Fri Jul 31 19:16:36 PDT 2026; root:xnu-12377.161.14~5/RELEASE_ARM64_T6030
  Available memory (MB): 18432
  Available CPU cores: 11

[github-actions]

Please add a reproduction in order for us to be able to investigate.

Depending on the quality of reproduction steps, this issue may be closed if no reproduction is provided.

Why was this issue marked with the invalid-reproduction label?

To be able to investigate, we need access to a reproduction to identify what triggered the issue. We prefer a link to a public GitHub repository created with create-payload-app@latest -t blank or a forked/branched version of this repository with tests added (more info in the reproduction-guide).

To make sure the issue is resolved as quickly as possible, please make sure that the reproduction is as minimal as possible. This means that you should remove unnecessary code, files, and dependencies that do not contribute to the issue. Ensure your reproduction does not depend on secrets, 3rd party registries, private dependencies, or any other data that cannot be made public. Avoid a reproduction including a whole monorepo (unless relevant to the issue). The easier it is to reproduce the issue, the quicker we can help.

Please test your reproduction against the latest version of Payload to make sure your issue has not already been fixed.

I added a link, why was it still marked?

Ensure the link is pointing to a codebase that is accessible (e.g. not a private repository). "example.com", "n/a", "will add later", etc. are not acceptable links -- we need to see a public codebase. See the above section for accepted links.

Useful Resources

• Reproduction Guide
• Contributing to Payload