{"record":{"id":"794aff6574f78d1b","repo":"twentyhq/twenty","slug":"failed-to-backfill-fields-widgets-for-workspace","errorCode":null,"errorMessage":"Failed to backfill FIELDS widgets for workspace ${workspaceId}","messagePattern":"Failed to backfill FIELDS widgets for workspace (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-workspace-command-1799000030000-backfill-fields-widget-new-field-default-visibility.command.ts","lineNumber":124,"sourceCode":"        await this.workspaceMigrationValidateBuildAndRunService.validateBuildAndRunLegacyWorkspaceMigration(\n          {\n            allFlatEntityOperationByMetadataName: {\n              pageLayoutWidget: {\n                flatEntityToCreate: [],\n                flatEntityToDelete: [],\n                flatEntityToUpdate: updatedWidgets,\n              },\n            },\n            workspaceId,\n            applicationUniversalIdentifier,\n          },\n        );\n\n      if (result.status === 'fail') {\n        this.logger.error(\n          `Failed to backfill FIELDS widgets for application ${applicationUniversalIdentifier} in workspace ${workspaceId}:\\n${JSON.stringify(result, null, 2)}`,\n        );\n        throw new Error(\n          `Failed to backfill FIELDS widgets for workspace ${workspaceId}`,\n        );\n      }\n\n      this.logger.log(\n        `Backfilled ${updatedWidgets.length} FIELDS widget(s) for application ${applicationUniversalIdentifier} in workspace ${workspaceId}`,\n      );\n    }\n  }\n}\n","sourceCodeStart":106,"sourceCodeEnd":135,"githubUrl":"https://github.com/twentyhq/twenty/blob/1f5dd2bbd2a8da3419c8cfd52dd545c0024df1a6/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-workspace-command-1799000030000-backfill-fields-widget-new-field-default-visibility.command.ts#L106-L135","documentation":"Thrown by the 2.9 workspace upgrade command that backfills FIELDS-type page layout widgets to set newFieldDefaultVisibility: true. It fires after validateBuildAndRunLegacyWorkspaceMigration returns status === 'fail' for a per-application pageLayoutWidget update batch. Each standard application is processed in its own loop iteration; the throw is per-application but reports the workspace.","triggerScenarios":"Upgrading to 2.9 on a workspace where one or more FIELDS widgets have a pageLayoutWidget record whose shape does not match what the migration builder expects — e.g. a widget missing the viewFilter/viewGrouping/viewSort metadata the builder reads, or a universalConfiguration that fails JSON validation. Also fires when the workspace's metadata schema for pageLayoutWidget lags behind the code version expected by this command.","commonSituations":"Self-hosted instances that skipped the 2.8 step, workspaces with custom/edited views whose widget JSON was hand-modified, or a DB that was partially restored. The preceding error log line names the failing applicationUniversalIdentifier and dumps the full result JSON, which holds the validation message.","solutions":["Read the preceding log: `Failed to backfill FIELDS widgets for application <id> in workspace <id>:` plus the JSON result — the result object carries the exact field-level failure.","Query the failing workspace's pageLayoutWidget rows for that applicationUniversalIdentifier (filter type = FIELDS) and compare each row's shape against the builder's expectations (presence of universalConfiguration, view fields).","Fix or remove the malformed widget row, then re-run the upgrade command for that workspace.","If many applications fail identically, suspect a schema drift — run any pending fast instance commands before the workspace command.","Confirm newFieldDefaultVisibility is a recognized field in the pageLayoutWidget entity definition for this server version."],"exampleFix":"// before\nthrow new Error(`Failed to backfill FIELDS widgets for workspace ${workspaceId}`);\n// after — surface the application id and the structured failure so triage does not require cross-referencing logs\ntype BuildFail = { status: 'fail'; error?: string; message?: string };\nconst fail = result as BuildFail;\nthrow new Error(\n  `Failed to backfill FIELDS widgets for application ${applicationUniversalIdentifier} ` +\n  `in workspace ${workspaceId}: ${fail.error ?? fail.message ?? JSON.stringify(result)}`,\n);","handlingStrategy":"try-catch","validationCode":"// Pre-check FIELDS widgets for the application before running the upgrade.\nconst widgets = await dataSource.query(\n  `SELECT id, \"applicationUniversalIdentifier\", \"universalConfiguration\" FROM ${workspaceSchema}.pageLayoutWidget WHERE type = 'FIELDS'`,\n);\nconst bad = widgets.filter((w: any) => w.universalConfiguration == null);\nif (bad.length) {\n  throw new Error(`FIELDS widgets with null universalConfiguration: ${bad.map((w: any) => w.id).join(', ')}`);\n}","typeGuard":"type BuildResult =\n  | { status: 'success' }\n  | { status: 'fail'; error?: string; message?: string };\nfunction isFail(r: BuildResult): r is Extract<BuildResult, { status: 'fail' }> {\n  return r.status === 'fail';\n}","tryCatchPattern":"try {\n  await backfillCommand.run();\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Failed to backfill FIELDS widgets')) {\n    failed.push({ workspaceId, err });\n    // do not abort the whole run; continue other applications/workspaces\n  } else throw err;\n}","preventionTips":["Back up the workspace metadata schema before any 2.9 upgrade run.","Run a fast instance command to bring the pageLayoutWidget schema current before the 2.9 workspace command.","In automation, isolate each application's backfill in its own try-catch so one bad widget does not poison the rest."],"tags":["database-migration","workspace-upgrade","page-layout-widget","nestjs"],"backgroundTag":null,"analyzedSha":"1f5dd2bbd2a8da3419c8cfd52dd545c0024df1a6","analyzedAt":"2026-08-12T15:37:27.593Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}