twentyhq/twenty · error · Error

Failed to backfill engine INDEX view(s) for workspace ${work

Error message

Failed to backfill engine INDEX view(s) for workspace ${workspaceId}

What it means

Thrown by the 2.26 command that demotes caller-authored INDEX views to key:null and backfills engine-owned INDEX views for manifest-installed applications. In runBackfillMigration, the command calls validateBuildAndRunLegacyWorkspaceMigration with view or viewField creation operations (views are committed before view fields across all applications). If the pipeline returns status 'fail', the detailed report is logged to logger.error and the generic error is thrown. The command is designed to be retry-safe: engine-owned INDEX views are neither demoted nor re-backfilled.

Source

Thrown at packages/twenty-server/src/database/commands/upgrade-version-command/2-26/2-26-workspace-command-1785255690000-demote-and-backfill-application-index-view.command.ts:410

    >;
  }): 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 engine INDEX view(s) for application ${applicationUniversalIdentifier} in workspace ${workspaceId}:\n${JSON.stringify(result, null, 2)}`,
      );

      throw new Error(
        `Failed to backfill engine INDEX view(s) for workspace ${workspaceId}`,
      );
    }
  }
}

View on GitHub (pinned to 1f5dd2bbd2)

Solutions

Read the logger.error JSON output — it includes the applicationUniversalIdentifier and JSON.stringify(result) with specific failure reasons
Flush flatViewMaps, flatViewFieldMaps, flatObjectMetadataMaps, flatFieldMetadataMaps from workspace cache and retry — the command is idempotent (already-backfilled viewFields are skipped, already-committed views are not re-created)
Verify the demotion phase completed: check for caller-authored INDEX views (key=ViewKey.INDEX, isSystemSideEffect=false) still present in the view table
Run with --dryRun to inspect the planned view and viewField operations

Defensive patterns

Strategy: retry

Validate before calling

// Before running, flush view, view field, object, and field metadata cache
await workspaceCacheService.invalidateAndRecompute(workspaceId, [
  'flatViewMaps',
  'flatViewFieldMaps',
  'flatObjectMetadataMaps',
  'flatFieldMetadataMaps',
]);

// Verify no caller-authored INDEX views remain (demotion should have cleared them)
const callerIndexViews = await viewRepository.count({
  where: { workspaceId, key: ViewKey.INDEX, isSystemSideEffect: false },
});

if (callerIndexViews > 0) {
  console.warn(`${callerIndexViews} caller-authored INDEX views remain — demotion phase may have failed`);
}

Try / catch

// Retry once after flushing cache — the command is retry-safe
// (engine-owned INDEX views are not re-backfilled on retry)
try {
  await command.runOnWorkspace({ workspaceId, options: { dryRun: false } });
} catch (error) {
  if (error.message.includes('Failed to backfill engine INDEX view')) {
    await invalidateIndexViewReconcileCache({
      workspaceId,
      workspaceMigrationRunnerService,
    });
    await command.runOnWorkspace({ workspaceId, options: { dryRun: false } });
  } else {
    throw error;
  }
}

Prevention

Run with --dryRun first to inspect the planned view and viewField operations per application
Verify the demotion phase completed before the backfill (check for surviving caller-authored INDEX views)
Invalidate the index view reconcile cache before retrying
Parse the logger.error JSON — it includes the applicationUniversalIdentifier and full failure details
The command is designed to be retry-safe: already-committed views and viewFields are skipped on retry

When it happens

Trigger: validateBuildAndRunLegacyWorkspaceMigration returns status 'fail' when creating UniversalFlatView or UniversalFlatViewField entities for an application's INDEX view. Caused by: the object metadata not existing for the application, a viewField referencing a fieldMetadata that doesn't exist in the workspace, a universal identifier collision with a surviving caller-authored view that wasn't demoted, stale cache, or a DB error.

Common situations: The demotion phase (viewRepository.update to key:null) partially failed, leaving caller-authored INDEX views that collide with the engine-owned INDEX view identifiers; a prior partial backfill created some viewFields but not others; cache doesn't reflect the demoted view state; the application object's fields were modified after cache was computed.

Related errors

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