twentyhq/twenty · error · Error

Failed to gate export/import command menu items by…

Error message

Failed to gate export/import command menu items by permission flag for workspace ${workspaceId}

What it means

Thrown by the 2.1 workspace upgrade command when validateBuildAndRunLegacyWorkspaceMigration returns 'fail' while gating export/import command menu items behind a permission-flag availability expression. The command logs the failure JSON then throws to stop the workspace upgrade.

Solutions

Read the logged validateAndBuildResult JSON for the exact expression or lookup error.
Recompute the workspace cache and retry.
Run --dryRun to confirm itemsToUpdate targets export/import items.
Verify the permission flag used in the expression exists in the installed build's permission definitions.

Defensive patterns

Strategy: validation

Validate before calling

// Dry-run to preview expression changes, and confirm the permission flag referenced in the expression is registered:
await workspaceCacheService.invalidate(workspaceId);
const flagRegistered = await permissionFlagExists(workspaceId, EXPORT_IMPORT_PERMISSION_FLAG_ID);
if (!flagRegistered) throw new Error('Permission flag not registered; cannot gate export/import items');

Try / catch

try {
  await command.runOnWorkspace({ workspaceId, options });
} catch (err) {
  logger.error(`Export/import gating failed for workspace ${workspaceId}`, err);
  failedWorkspaces.push(workspaceId);
}

Prevention

Run --dryRun to confirm itemsToUpdate targets export/import items.
Verify the permission flag used in the expression exists in the build's permission definitions.
Recompute the cache before running.
Catch per-workspace at the runner.

When it happens

Trigger: Running the 2.1 permission-flag gating on a workspace whose export/import command menu items are missing from cache, or whose new availability expression the builder's expression validator rejects.

Common situations: Stale cache so the export/import items resolve to undefined; permission flag identifier referenced in the expression not registered in the build; partial prior run left items inconsistent.

Related errors

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

Appendix: source

Thrown at packages/twenty-server/src/database/commands/upgrade-version-command/2-1/2-1-workspace-command-1790000000000-gate-export-import-command-menu-items-by-permission-flag.command.ts:132

          allFlatEntityOperationByMetadataName: {
            commandMenuItem: {
              flatEntityToCreate: [],
              flatEntityToDelete: [],
              flatEntityToUpdate: itemsToUpdate,
            },
          },
          workspaceId,
          applicationUniversalIdentifier:
            twentyStandardFlatApplication.universalIdentifier,
        },
      );

    if (validateAndBuildResult.status === 'fail') {
      this.logger.error(
        `Failed to update command menu item availability expressions:\n${JSON.stringify(validateAndBuildResult, null, 2)}`,
      );

      throw new Error(
        `Failed to gate export/import command menu items by permission flag for workspace ${workspaceId}`,
      );
    }

    this.logger.log(
      `Successfully updated ${itemsToUpdate.length} command menu item availability expression(s) for workspace ${workspaceId}`,
    );
  }
}

View on GitHub (pinned to 1f5dd2bbd2)