twentyhq/twenty · critical · Error

Failed to backfill record page(s) for workspace ${workspaceI

Error message

Failed to backfill record page(s) for workspace ${workspaceId}

What it means

Thrown by the large 2.31 command that backfills record pages (views, view-fields, view-field-groups, page-layouts, tabs, widgets) per application. It builds allFlatEntityOperationByMetadataName and submits via validateBuildAndRunLegacyWorkspaceMigration; on status === 'fail' it logs the report (scoped to the applicationUniversalIdentifier) and throws. The report names which flat entity type and which entity failed.

Source

Thrown at packages/twenty-server/src/database/commands/upgrade-version-command/2-31/2-31-workspace-command-1786437482000-backfill-record-page.command.ts:715

    >;
  }): Promise<void> {
    const result =
      await this.workspaceMigrationValidateBuildAndRunService.validateBuildAndRunLegacyWorkspaceMigration(
        {
          isSystemBuild: true,
          workspaceId,
          applicationUniversalIdentifier,
          allFlatEntityOperationByMetadataName:
            allFlatEntityOperationByMetadataName as never,
        },
      );

    if (result.status === 'fail') {
      this.logger.error(
        `Failed to backfill record page(s) for application ${applicationUniversalIdentifier} in workspace ${workspaceId}:\n${JSON.stringify(result, null, 2)}`,
      );

      throw new Error(
        `Failed to backfill record page(s) for workspace ${workspaceId}`,
      );
    }
  }
}

View on GitHub (pinned to 1f5dd2bbd2)

Solutions

Read the logged JSON report — note the metadata name (view/viewField/pageLayout/...), the entity universalIdentifier, and the error code.
For a missing-dependency error, ensure the prerequisite object/field exists (run the earlier upgrade commands first).
For a collision, remove or reconcile the conflicting existing entity for that workspace.
Invalidate and recompute the workspace cache, then re-run the 2.31 command for the workspace.

Defensive patterns

Strategy: try-catch

Validate before calling

// Per-application, assert referenced objects/views exist before building the batch:
const missing = requiredObjectUIs.filter(ui => !isDefined(flatObjectMetadataMaps.byUniversalIdentifier[ui]));
if (missing.length > 0) { /* run prerequisite upgrades first */ }

Try / catch

try {
  await command.runOnWorkspace({ workspaceId, options });
} catch (e) {
  // e.message embeds the per-application report; parse and continue per-workspace
  logger.error({ workspaceId, err: e.message }, 'record page backfill failed');
}

Prevention

Run all earlier major-version upgrades first so base objects/views exist.
Invalidate the workspace cache before retrying so the build sees fresh metadata.
Parse the logged report to target the specific failing entity type.

When it happens

Trigger: A referenced object/field/relation universal identifier is absent in the workspace; a view/page-layout universalIdentifier already exists with a conflicting shape; a system view key resolves to a layout whose dependencies are missing; the applicationUniversalIdentifier does not match a registered application for the workspace.

Common situations: Cross-version upgrade where intermediate commands that create the base objects/views were skipped; workspaces with heavily customised record pages that collide with the system layout being backfilled; stale workspace cache after an out-of-band metadata edit.

Related errors

AI-assisted analysis of twentyhq/twenty@1f5dd2bbd2 (2026-08-12). Data as JSON: /api/errors/ee5c2790de70bae8. Report an issue: GitHub.