{"record":{"id":"e97fa662027146a8","repo":"Budibase/budibase","slug":"cannot-rename-a-linked-column","errorCode":null,"errorMessage":"Cannot rename a linked column.","messagePattern":"Cannot rename a linked column\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/server/src/sdk/workspace/tables/internal/index.ts","lineNumber":120,"sourceCode":"  table = checkAutoColumns(table, oldTable)\n\n  // saving a table is a complex operation, involving many different steps, this\n  // has been broken out into a utility to make it more obvious/easier to manipulate\n  const tableSaveFunctions = new TableSaveFunctions({\n    userId: opts?.userId,\n    oldTable,\n    importRows: opts?.rowsToImport,\n  })\n  table = await tableSaveFunctions.before(table)\n\n  let renaming = opts?.renaming\n  if (renaming && renaming.old === renaming.updated) {\n    renaming = undefined\n  }\n\n  // rename row fields when table column is renamed\n  if (renaming && table.schema[renaming.updated]?.type === FieldType.LINK) {\n    throw new Error(\"Cannot rename a linked column.\")\n  }\n\n  let pendingColumnRenames = oldTable?.pendingColumnRenames\n    ? oldTable.pendingColumnRenames\n    : []\n  if (renaming) {\n    pendingColumnRenames = mergePendingColumnRenames(\n      pendingColumnRenames,\n      renaming\n    )\n  }\n  if (pendingColumnRenames.length > 0) {\n    table.pendingColumnRenames = pendingColumnRenames\n  } else {\n    delete table.pendingColumnRenames\n  }\n\n  table = await tableSaveFunctions.mid(table, renaming)","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/server/src/sdk/workspace/tables/internal/index.ts#L102-L138","documentation":"When save() is called with a renaming option and the target column is a relationship (FieldType.LINK), the rename is rejected because renaming linked columns would break the link documents between tables. Relationship columns must be managed through link operations instead.","triggerScenarios":"Calling sdk.tables.saveTable with opts.renaming = { old, updated } where table.schema[updated].type === FieldType.LINK (a relationship column), including via the column-rename endpoint.","commonSituations":"Renaming a user relationship column via the builder/API during the user-column migration flow; scripted table refactors that blindly rename all columns.","solutions":["Skip link-type columns in your rename loop and only rename non-relationship columns","Convert the relationship to a bb-reference column first (see tables/migration.ts), then rename it","Recreate the relationship column with the desired name and re-establish links","Leave the link column name as-is; relationship names are display labels in most UIs"],"exampleFix":"// before\nif (column.type === FieldType.LINK) {\n  await sdk.tables.saveTable(table, { renaming: { old: name, updated: newName } })\n}\n// after\nif (column.type !== FieldType.LINK) {\n  await sdk.tables.saveTable(table, { renaming: { old: name, updated: newName } })\n}","handlingStrategy":"validation","validationCode":"function canRename(table: Table, renaming: { old: string, updated: string }): boolean {\n  return table.schema[renaming.updated]?.type !== FieldType.LINK\n}","typeGuard":"function isLinkColumn(col: FieldSchema | undefined): boolean {\n  return col?.type === FieldType.LINK\n}","tryCatchPattern":"try {\n  await sdk.tables.saveTable(table, { renaming })\n} catch (e) {\n  if (e.message === 'Cannot rename a linked column.') {\n    // skip the rename for this relationship column\n  }\n}","preventionTips":["Filter out FieldType.LINK columns from any bulk rename operation","Rename relationships by recreating the column and re-establishing links","Check the target column type before invoking a rename"],"tags":["schema","relationships","rename"],"backgroundTag":"linked-column-rename-rejected","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}