Bug: Array field named `numbers` causes `TypeError: Cannot read properties of undefined (reading 'referencedTable')`

[reezy24]

Describe the Bug

Description

When a Payload CMS collection has an array field named numbers, any query against that collection throws:

TypeError: Cannot read properties of undefined (reading 'referencedTable')
    at normalizeRelation (drizzle-orm/src/relations.ts:572)
    at PgDialect.buildRelationalQueryWithoutPK (drizzle-orm/src/pg-core/dialect.ts:1283)

The same issue occurs with an array field named texts.

Root cause

The bug is in Payload's @payloadcms/drizzle package (packages/drizzle/src/find/buildFindManyArgs.ts, lines 100-128).

Payload uses a naming convention where hasManyNumber fields (number fields with hasMany: true) get a dedicated table named ${collectionTable}_numbers and a drizzle relation keyed _numbers. Similarly, hasManyText fields get ${collectionTable}_texts / _texts.

When building a find query, buildFindManyArgs checks whether these tables exist to decide whether to include the _numbers / _texts relations in drizzle's with clause:

// buildFindManyArgs.ts line 110
if (adapter.tables[`${tableName}_numbers`] && withTabledFields.numbers) {
  result.with._numbers = { ... }
}

However, an array field named numbers also creates a table called ${collectionTable}_numbers — but its drizzle relation is keyed as numbers, not _numbers. The table existence check is a false positive: it matches the array sub-table and incorrectly adds _numbers to the with clause.

When drizzle resolves the query, it looks up tableConfig.relations['_numbers'], which doesn't exist (only 'numbers' does), resulting in undefined. It then calls normalizeRelation(schema, tableNamesMap, undefined), which tries to access undefined.referencedTable and throws the TypeError.

Workaround

Rename the array field to something that doesn't collide with the internal suffix convention — e.g. drawNumbers instead of numbers.

Suggested fix

In buildFindManyArgs.ts, replace the table existence checks with relation existence checks:

// Before (buggy):
if (adapter.tables[`${tableName}_numbers`] && withTabledFields.numbers) {

// After (fixed):
if (adapter.rawRelations[tableName]?.['_numbers'] && withTabledFields.numbers) {

Apply the same pattern for _texts and _rels.

Alternative fix: highlight in the documentation that the words numbers, texts and rels cannot be used as field names.

Link to the code that reproduces this issue

https://github.com/reezy24/payload-referenced-table-bug

Reproduction Steps

Create a collection with the following and add it to your payload-config.ts.

// src/collections/Draws.ts
import type { CollectionConfig } from 'payload'

export const Draws: CollectionConfig = {
  slug: 'draws',
  fields: [
    {
      name: 'numbers',  // <-- this name triggers the bug
      type: 'array',
      required: true,
      fields: [
        {
          name: 'drawPosition',
          type: 'number',
          required: true,
          min: 1,
        },
      ],
    },
  ],
}

Start the dev server, go to the admin dashboard and view the collection page for Draws - you will see an error in the dev server logs as above.

If you rename the field to "drawNumbers", the error goes away.

Which area(s) are affected?

db: vercel-postgres

Environment Info

➜  referenced-table-bug git:(main) pnpm payload info

> referenced-table-bug@1.0.0 payload /Users/reez/Documents/code/referenced-table-bug
> cross-env NODE_OPTIONS=--no-deprecation payload info

npm warn Unknown env config "npm-globalconfig". This will stop working in the next major version of npm.
npm warn Unknown env config "verify-deps-before-run". This will stop working in the next major version of npm.
npm warn Unknown env config "_jsr-registry". This will stop working in the next major version of npm.

Binaries:
  Node: 24.13.1
  npm: 11.8.0
  Yarn: N/A
  pnpm: 10.33.0
Relevant Packages:
  payload: 3.81.0
  next: 16.2.1
  @payloadcms/db-vercel-postgres: 3.81.0
  @payloadcms/drizzle: 3.81.0
  @payloadcms/graphql: 3.81.0
  @payloadcms/next/utilities: 3.81.0
  @payloadcms/richtext-lexical: 3.81.0
  @payloadcms/translations: 3.81.0
  @payloadcms/ui/shared: 3.81.0
  react: 19.2.4
  react-dom: 19.2.4
Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.3.0: Wed Jan 28 20:56:42 PST 2026; root:xnu-12377.91.3~2/RELEASE_ARM64_T8142
  Available memory (MB): 32768
  Available CPU cores: 10