Budibase/budibase · error

Unable to lookup relationships - undefined column properties

Error message

Unable to lookup relationships - undefined column properties.

What it means

lookupRelations resolves a relationship column into (relatedTableId, lookupField, fieldName) by inspecting the column's type. For many-to-one it uses field.tableId/field.foreignKey; for other relationship types the analogous properties. If after the branch any of these is falsy, the relationship column is malformed or an unsupported shape, so it throws rather than producing a broken query.

Source

Thrown at packages/server/src/api/controllers/row/ExternalRequest.ts:454

        !field.fieldName ||
        isOneSide(field)
      ) {
        continue
      }
      let relatedTableId: string | undefined,
        lookupField: string | undefined,
        fieldName: string | undefined
      if (isManyToMany(field)) {
        relatedTableId = field.through
        lookupField = primaryKey
        fieldName = field.throughTo || primaryKey
      } else if (isManyToOne(field)) {
        relatedTableId = field.tableId
        lookupField = field.foreignKey
        fieldName = field.fieldName
      }
      if (!relatedTableId || !lookupField || !fieldName) {
        throw new Error(
          "Unable to lookup relationships - undefined column properties."
        )
      }

      if (!lookupField || !row?.[lookupField]) {
        continue
      }
      const endpoint = getEndpoint(relatedTableId, Operation.READ)
      const relatedTable = this.tables[endpoint.entityId]
      if (!relatedTable) {
        throw new Error("unable to find related table")
      }
      const response = await makeExternalQuery({
        endpoint,
        filters: {
          equal: {
            [fieldName]: row[lookupField],
          },

View on GitHub (pinned to a81a902e9a)

Solutions

1. Re-fetch/sync the datasource schema so relationship columns carry tableId, foreignKey and fieldName
2. Fix the relationship column definition to set the correct foreignKey/tableId
3. Verify the column is a supported relationship type (one-to-many, many-to-many, many-to-one)

Example fix

// before
// column defined without foreign key
{ name: "customerContacts", type: "link", tableId: "customers" }
// after
{ name: "customerContacts", type: "link", tableId: "customers", foreignKey: "customerId", fieldName: "customerId" }

const col = table.schema[fieldName]
const isValidLink = col && (col.type === "link" || col.type === "json") &&
  (isManyToOne(col) ? !!(col.tableId && col.foreignKey) : !!(col.tableId && col.fieldName))
if (!isValidLink) throw new Error(`${fieldName} is not a fully-defined relationship`)

const isCompleteLink = (col: unknown): col is { tableId: string; foreignKey: string; fieldName: string } =>
  typeof col === "object" && col !== null &&
  "tableId" in col && "foreignKey" in col && "fieldName" in col

When it happens

Trigger: Calling related() on a row where the relationship column in the external table definition lacks tableId/foreignKey/fieldName — e.g. schema out of sync, a relationship column defined without a foreign key, or a column misdetected as a relationship type.

Common situations: Datasource schema not re-fetched after the underlying DB schema changed; manually edited datasource config missing `foreignKey`; datasource connector returning partial column metadata; mismatched relationship direction detection (isManyToOne/isOneToMany both false).

Related errors

• unable to find related table
• Table ID is unknown, cannot find table
• Cannot fetch row by ID "${rowId}"
• Unable to generate link schema, no primary keys
• Cannot rename a linked column.

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/1306cc3caf470398. Report an issue: GitHub.