remix-run/remix · error · Error

Relation key mismatch between "{sourceTableName}" ({sourceKe

Error message

Relation key mismatch between "{sourceTableName}" ({sourceKey}) and "{targetTableName}" ({targetKey})

What it means

Relations match source and target columns pairwise; the number of key columns on each side must be equal. This error fires when e.g. the source key lists one column but the target key lists two, making the join unresolvable.

Source

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

  if (options === true) {
    return { ...defaultTimestampConfig }
  }

  return {
    createdAt: options.createdAt ?? defaultTimestampConfig.createdAt,
    updatedAt: options.updatedAt ?? defaultTimestampConfig.updatedAt,
  }
}

function assertKeyLengths(
  sourceTableName: string,
  targetTableName: string,
  sourceKey: string[],
  targetKey: string[],
): void {
  if (sourceKey.length !== targetKey.length) {
    throw new Error(
      'Relation key mismatch between "' +
        sourceTableName +
        '" (' +
        sourceKey.join(', ') +
        ') and "' +
        targetTableName +
        '" (' +
        targetKey.join(', ') +
        ')',
    )
  }
}

type CreateRelationOptions<
  source extends AnyTable,
  target extends AnyTable,
  cardinality extends RelationCardinality,
> = {

View on GitHub (pinned to 9696913134)

Solutions

1. Make sourceKey and targetKey arrays the same length, pairing each column correctly
2. For composite keys, list columns in matching order on both sides
3. Re-check which side needs multiple columns — usually both or neither

Example fix

// before
belongsTo(users, { sourceKey: ['tenantId','userId'], targetKey: ['id'] })
// after
belongsTo(users, { sourceKey: ['tenantId','userId'], targetKey: ['tenantId','id'] })

if (sourceKey.length !== targetKey.length) throw new Error('relation key arity mismatch')

When it happens

Trigger: belongsTo(..., { sourceKey: ['tenantId','id'], targetKey: ['id'] }) or similar asymmetric key arrays in a relation definition.

Common situations: Composite foreign keys where one side was updated but not the other; copy-pasting a single-column relation and adding a column to only one key list.

Related errors

• hasManyThrough expects a through relation whose source table
• create({ returnRow: true }) failed to load inserted row
• Relation "' + relationName + '" is not defined for source ta
• hasManyThrough relation is missing through metadata
• Unknown transaction token: + token.id

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