remix-run/remix · error · Error

Table "{tableName}" primaryKey column "{key}" does not exist

Error message

Table "{tableName}" primaryKey column "{key}" does not exist

What it means

Each column named in the table's primaryKey option must actually exist in the columns definition. This error fires when a key column name does not match any defined column.

Source

Thrown at packages/data-table/src/lib/table.ts:1109

  if (primaryKey === undefined) {
    if (!Object.prototype.hasOwnProperty.call(columns, 'id')) {
      throw new Error(
        'Table "' + tableName + '" must include an "id" column or an explicit primaryKey',
      )
    }

    return ['id']
  }

  let keys = Array.isArray(primaryKey) ? [...primaryKey] : [primaryKey]

  if (keys.length === 0) {
    throw new Error('Table "' + tableName + '" primaryKey must contain at least one column')
  }

  for (let key of keys) {
    if (!Object.prototype.hasOwnProperty.call(columns, key)) {
      throw new Error('Table "' + tableName + '" primaryKey column "' + key + '" does not exist')
    }
  }

  return keys
}

function normalizeKeySelector<table extends AnyTable>(
  table: table,
  selector: KeySelector<table> | undefined,
  optionName: string,
  defaultValue: readonly string[],
): string[] {
  return normalizeKeysForTable(table, selector, optionName, defaultValue)
}

function normalizeKeysForTable(
  table: AnyTable,
  selector: string | readonly string[] | undefined,

View on GitHub (pinned to 9696913134)

Solutions

1. Match the primaryKey names exactly to the column keys in the definition
2. Rename either the column or the key so they agree
3. Add the missing column if it was unintentionally omitted

Example fix

// before
createTable('t', { user_id: column.uuid() }, { primaryKey: ['userId'] })
// after
createTable('t', { user_id: column.uuid() }, { primaryKey: ['user_id'] })

for (const key of keys) {
  if (!(key in columns)) throw new Error(`primaryKey column ${key} not defined`)
}

When it happens

Trigger: primaryKey: ['userId'] when the column is defined as user_id, or after renaming/removing a column without updating the primaryKey option.

Common situations: Naming-convention drift (camelCase vs snake_case), partial schema migrations, or hand-written key names with typos.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Table "{tableName}" must include an "id" column or an explic
• Table "{tableName}" primaryKey must contain at least one col
• onDelete() requires references() to be set first
• onUpdate() requires references() to be set first
• create({ returnRow: true }) requires primary key values for

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/ac994ec562643761. Report an issue: GitHub.