Budibase/budibase · error · Error

Cannot overwrite existing column.

Error message

Cannot overwrite existing column.

What it means

When a table containing a link column is saved, tableSaved mirrors the link by writing a reciprocal link column named field.fieldName into the linked table. Before writing, it checks the linked table's existing schema: if a column with that name already exists and its definition is not equivalent to the link field that would be written, the save is aborted so an unrelated user column is not clobbered by the relationship metadata.

Source

Thrown at packages/server/src/db/linkedRows/LinkController.ts:398

        schema[fieldName] = fields.linkerField
        const linkedField = fields.linkedField

        if (field.autocolumn) {
          linkedField.autocolumn = field.autocolumn
          linkedField.subtype = field.subtype
        }

        if (field.aiGenerated) {
          linkedField.aiGenerated = field.aiGenerated
        }

        // check the linked table to make sure we aren't overwriting an existing column
        const existingSchema = linkedTable.schema[field.fieldName]
        if (
          existingSchema != null &&
          !this.areLinkSchemasEqual(existingSchema, linkedField)
        ) {
          throw new Error("Cannot overwrite existing column.")
        }
        // create the link field in the other table
        linkedTable.schema[field.fieldName] = linkedField
        const response = await this._db.put(linkedTable)
        // special case for when linking back to self, make sure rev updated
        if (linkedTable._id === table._id) {
          table._rev = response.rev
        }
      }
    }
    return table
  }

  /**
   * Update a table, this means if a field is removed need to handle removing from other table and removing
   * any link docs that pertained to it.
   * @returns The table which has been saved, same response as with the tableSaved function.
   */

View on GitHub (pinned to a81a902e9a)

Solutions

1. Rename the link column's fieldName (the name on the other table) to something not already present in the linked table's schema, then save again.
2. If the existing column is a leftover/stale link column, remove it from the linked table first and re-create the relationship.
3. If the schemas should match but don't, delete both link columns and re-create the relationship fresh so the reciprocal field is regenerated consistently.
4. Check for self-links: when field.tableId equals the table's own _id, ensure the reciprocal fieldName is unique within that one schema.

Example fix

// before
{ name: "Orders", type: "link", tableId: "ta_customers", fieldName: "status" } // collides with existing "status" column
// after
{ name: "Orders", type: "link", tableId: "ta_customers", fieldName: "orders" } // unique name on linked table

const linkedTable = await db.get(table.field.tableId)
if (linkedTable.schema[table.field.fieldName] != null) {
  throw new Error(`Column "${table.field.fieldName}" already exists on the linked table`)
}

try {
  await saveTable(table)
} catch (err) {
  if (err.message === "Cannot overwrite existing column.") {
    // prompt user to pick a different reciprocal column name
  } else throw err
}

When it happens

Trigger: Saving/updating a table (tableSaved via tableUpdated or updateLinks) where a link field's fieldName collides with an existing column of the same name in the target table, and the existing column is not an equal link schema.

Common situations: Naming the link column the same as a column that already exists on the other table (e.g. "customer" exists on both); renaming a link column to a taken name; linking a table to itself and reusing an existing field name; restoring a table definition from an export where the reciprocal column drifted.

Related errors

• 1:N Relationship Error: Record already linked to another.
• Found ${visibleNames.length} table(s) in the "${this.config.
• DB does not exist
• CouchDB error: ${err.message}
• TableImportError(errors)

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