Skip to content

The open alternative to Salesforce, designed for AI.

Surface the deferred action conflict as a conflict error (#26521)

Charles Bochet560e5e32b291
diff --git a/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx b/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx
index f1a3a28693e..c7ec881f508 100644
--- a/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx
+++ b/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx
@@ -175,5 +175,6 @@ When something goes wrong, the metadata diff and named errors let you place the
- **Registration ownership error** — the sync is refused because the app's `universalIdentifier` belongs to another workspace, or to no workspace at all; see [Registration ownership](/developers/extend/apps/operations/publishing#registration-ownership).
- **Sync / migration error** — the build succeeds but applying the diff fails, naming the entity and `universalIdentifier`; fix the conflicting metadata.
- **Dependencies size error** — the sync or install fails because the app's production `dependencies` are too large to install as a runtime layer (`LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED`); move packages your logic functions do not import at runtime (UI libraries, dev tooling) to `devDependencies`.
+- **Deferred migration in progress** — the sync is refused because a background data model migration from an earlier sync is still running (`DEFERRED_WORKSPACE_MIGRATION_ACTIONS_IN_PROGRESS`); wait for it to finish, then sync again.
- **App code runtime error** — the sync succeeds but your logic functions or components misbehave at runtime; check [function logs](/developers/extend/apps/operations/cli).
- **Local instance state** — none of the above and the workspace still looks wrong; work down the recovery ladder.
diff --git a/packages/twenty-server/docs/DEFERRED_WORKSPACE_MIGRATION_ACTIONS.md b/packages/twenty-server/docs/DEFERRED_WORKSPACE_MIGRATION_ACTIONS.md
index b2768168508..a5af52fb0a4 100644
--- a/packages/twenty-server/docs/DEFERRED_WORKSPACE_MIGRATION_ACTIONS.md
+++ b/packages/twenty-server/docs/DEFERRED_WORKSPACE_MIGRATION_ACTIONS.md
@@ -162,8 +162,8 @@ Delivery, each PR merged on its own behind the flag:
| 1 | Table, `DEFERRABLE_WORKSPACE_MIGRATION_ACTIONS`, handler contract, runner persistence, deferred action runner and job with retries and timeout; `create_index` and `delete_logicFunction`; `afterCommitSideEffects` removed. |
| 2 | Recovery: cron resetting `IN_PROGRESS` rows past the timeout and enqueueing workspaces with `PENDING` rows; CLI retry of `FAILED` rows; job deduplication per workspace and retry backoff; metrics on duration and on rows by status. |
| 3 | Refuse schema-affecting migrations while the workspace has in-flight deferred builds: see above. |
-| 4 | Error surfacing and admin retry of `FAILED` rows from the admin panel: runner codes sent as `subCode` (today `extensions.code` is overwritten by the GraphQL error code), object and field exception handlers map the new codes to `ConflictError`, dedicated front message with the pending count, SDK CLI reads `subCode` and `userFriendlyMessage`. |
-| 5 | Foreign keys: `ADD CONSTRAINT ... NOT VALID` for join columns created in the same action, plus a deferrable `create_fieldMetadata` action running `VALIDATE CONSTRAINT` with the constraint name in its payload. |
+| 4 | Error surfacing: the object, field and index exception handlers map `DEFERRED_WORKSPACE_MIGRATION_ACTIONS_IN_PROGRESS` to a `ConflictError` carrying `subCode` and `userFriendlyMessage`; the SDK CLI shows that message with a wait-and-retry hint. |
+| 5 | Admin retry of `FAILED` rows from the admin panel, then foreign keys: `ADD CONSTRAINT ... NOT VALID` for join columns created in the same action, plus a deferrable `create_fieldMetadata` action running `VALIDATE CONSTRAINT` with the constraint name in its payload. |
| 6 | Enable the flag for the affected self-hosted workspace, then cloud, then default on and remove the flag. |
Migration: one fast instance command in 2.42 creating the table. No backfill.
@@ -178,7 +178,11 @@ Tested in PR 2, manually on the same data: two object creations with the worker
Tested in PR 3, manually on the same data: a second object creation is refused while the first one's index builds are pending, and accepted once they drain; a view is created while builds are pending; a pending logic function cleanup on its own refuses nothing; with the flag off nothing is refused. Integration: the deferred, index and object metadata suites pass.
-Known limitation until PR 4: the refusal reaches the client as `INTERNAL_SERVER_ERROR` with the right `userFriendlyMessage`, because the GraphQL error code overwrites `extensions.code`.
+### Surfacing the refusal
+
+A refused migration reaches the client as a `ConflictError`: `extensions.code` is `CONFLICT`, `extensions.subCode` is `DEFERRED_WORKSPACE_MIGRATION_ACTIONS_IN_PROGRESS` and `extensions.userFriendlyMessage` explains the wait. `workspaceMigrationRunnerExceptionFormatter` produces it, and the object, field and index GraphQL exception handlers now delegate to that same formatter for runner exceptions, since those resolvers catch them before the workspace migration interceptor sees them.
+
+The front needs nothing of its own: `getToastOptionsFromError` already reads `userFriendlyMessage` off the extensions, so the settings toast shows that sentence. The SDK CLI shows it in place of the server message, which names a workspace by uuid, and adds a hint telling the user to wait for the background change to finish and sync again.
## Open questions
diff --git a/packages/twenty-server/src/engine/metadata-modules/field-metadata/utils/field-metadata-graphql-api-exception-handler.util.ts b/packages/twenty-server/src/engine/metadata-modules/field-metadata/utils/field-metadata-graphql-api-exception-handler.util.ts
index 0291d8c07c4..82cd7bed1b9 100644
--- a/packages/twenty-server/src/engine/metadata-modules/field-metadata/utils/field-metadata-graphql-api-exception-handler.util.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/field-metadata/utils/field-metadata-graphql-api-exception-handler.util.ts
@@ -13,8 +13,14 @@ import {
import { InvalidMetadataException } from 'src/engine/metadata-modules/utils/exceptions/invalid-metadata.exception';
import { WorkspaceMigrationBuilderException } from 'src/engine/workspace-manager/workspace-migration/exceptions/workspace-migration-builder-exception';
import { workspaceMigrationBuilderGraphqlApiExceptionHandler } from 'src/engine/workspace-manager/workspace-migration/interceptors/utils/workspace-migration-builder-graphql-api-exception-handler.util';
+import { workspaceMigrationRunnerExceptionFormatter } from 'src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-runner-exception-formatter';
+import { WorkspaceMigrationRunnerException } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/exceptions/workspace-migration-runner.exception';
export const fieldMetadataGraphqlApiExceptionHandler = (error: unknown) => {
+ if (error instanceof WorkspaceMigrationRunnerException) {
+ workspaceMigrationRunnerExceptionFormatter(error);
+ }
+
if (error instanceof WorkspaceMigrationBuilderException) {
return workspaceMigrationBuilderGraphqlApiExceptionHandler(error);
}
diff --git a/packages/twenty-server/src/engine/metadata-modules/index-metadata/utils/index-metadata-graphql-api-exception-handler.util.ts b/packages/twenty-server/src/engine/metadata-modules/index-metadata/utils/index-metadata-graphql-api-exception-handler.util.ts
index 30fe6905059..1cb73c82e76 100644
--- a/packages/twenty-server/src/engine/metadata-modules/index-metadata/utils/index-metadata-graphql-api-exception-handler.util.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/index-metadata/utils/index-metadata-graphql-api-exception-handler.util.ts
@@ -13,8 +13,14 @@ import {
} from 'src/engine/metadata-modules/index-metadata/index-field-metadata.exception';
import { WorkspaceMigrationBuilderException } from 'src/engine/workspace-manager/workspace-migration/exceptions/workspace-migration-builder-exception';
import { workspaceMigrationBuilderGraphqlApiExceptionHandler } from 'src/engine/workspace-manager/workspace-migration/interceptors/utils/workspace-migration-builder-graphql-api-exception-handler.util';
+import { workspaceMigrationRunnerExceptionFormatter } from 'src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-runner-exception-formatter';
+import { WorkspaceMigrationRunnerException } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/exceptions/workspace-migration-runner.exception';
export const indexMetadataGraphqlApiExceptionHandler = (error: Error) => {
+ if (error instanceof WorkspaceMigrationRunnerException) {
+ workspaceMigrationRunnerExceptionFormatter(error);
+ }
+
if (error instanceof WorkspaceMigrationBuilderException) {
return workspaceMigrationBuilderGraphqlApiExceptionHandler(error);
}
diff --git a/packages/twenty-server/src/engine/metadata-modules/object-metadata/utils/object-metadata-graphql-api-exception-handler.util.ts b/packages/twenty-server/src/engine/metadata-modules/object-metadata/utils/object-metadata-graphql-api-exception-handler.util.ts
index d05c68dff5f..b5dfa8167c0 100644
--- a/packages/twenty-server/src/engine/metadata-modules/object-metadata/utils/object-metadata-graphql-api-exception-handler.util.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/object-metadata/utils/object-metadata-graphql-api-exception-handler.util.ts
@@ -14,8 +14,14 @@ import {
import { InvalidMetadataException } from 'src/engine/metadata-modules/utils/exceptions/invalid-metadata.exception';
import { WorkspaceMigrationBuilderException } from 'src/engine/workspace-manager/workspace-migration/exceptions/workspace-migration-builder-exception';
import { workspaceMigrationBuilderGraphqlApiExceptionHandler } from 'src/engine/workspace-manager/workspace-migration/interceptors/utils/workspace-migration-builder-graphql-api-exception-handler.util';
+import { workspaceMigrationRunnerExceptionFormatter } from 'src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-runner-exception-formatter';
+import { WorkspaceMigrationRunnerException } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/exceptions/workspace-migration-runner.exception';
export const objectMetadataGraphqlApiExceptionHandler = (error: unknown) => {
+ if (error instanceof WorkspaceMigrationRunnerException) {
+ workspaceMigrationRunnerExceptionFormatter(error);
+ }
+
if (error instanceof WorkspaceMigrationBuilderException) {
return workspaceMigrationBuilderGraphqlApiExceptionHandler(error);
}
diff --git a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/interceptors/__tests__/workspace-migration-runner-exception-formatter.spec.ts b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/interceptors/__tests__/workspace-migration-runner-exception-formatter.spec.ts
new file mode 100644
index 00000000000..6730728de59
--- /dev/null
+++ b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/interceptors/__tests__/workspace-migration-runner-exception-formatter.spec.ts
@@ -0,0 +1,45 @@
+import { ErrorCode } from 'src/engine/core-modules/graphql/utils/graphql-errors.util';
+import { workspaceMigrationRunnerExceptionFormatter } from 'src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-runner-exception-formatter';
+import {
+ WorkspaceMigrationRunnerException,
+ WorkspaceMigrationRunnerExceptionCode,
+} from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/exceptions/workspace-migration-runner.exception';
+
+describe('workspaceMigrationRunnerExceptionFormatter', () => {
+ it('should format deferred actions in progress as a conflict carrying its sub code and message', () => {
+ const exception = new WorkspaceMigrationRunnerException({
+ message:
+ '4 deferred schema action(s) are still running on workspace 2020',
+ code: WorkspaceMigrationRunnerExceptionCode.DEFERRED_WORKSPACE_MIGRATION_ACTIONS_IN_PROGRESS,
+ });
+
+ expect(() => workspaceMigrationRunnerExceptionFormatter(exception)).toThrow(
+ expect.objectContaining({
+ message: exception.message,
+ extensions: expect.objectContaining({
+ code: ErrorCode.CONFLICT,
+ subCode:
+ WorkspaceMigrationRunnerExceptionCode.DEFERRED_WORKSPACE_MIGRATION_ACTIONS_IN_PROGRESS,
+ userFriendlyMessage: exception.userFriendlyMessage,
+ }),
+ }),
+ );
+ });
+
+ it('should keep formatting other runner exceptions as internal server errors', () => {
+ expect(() =>
+ workspaceMigrationRunnerExceptionFormatter(
+ new WorkspaceMigrationRunnerException({
+ message: 'Application not found',
+ code: WorkspaceMigrationRunnerExceptionCode.APPLICATION_NOT_FOUND,
+ }),
+ ),
+ ).toThrow(
+ expect.objectContaining({
+ extensions: expect.objectContaining({
+ code: ErrorCode.INTERNAL_SERVER_ERROR,
+ }),
+ }),
+ );
+ });
+});
diff --git a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-runner-exception-formatter.ts b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-runner-exception-formatter.ts
index 59e01d1deb4..7fc6eccbb88 100644
--- a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-runner-exception-formatter.ts
+++ b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-runner-exception-formatter.ts
@@ -1,5 +1,6 @@
import {
BaseGraphQLError,
+ ConflictError,
ErrorCode,
} from 'src/engine/core-modules/graphql/utils/graphql-errors.util';
import {
@@ -10,6 +11,16 @@ import {
export const workspaceMigrationRunnerExceptionFormatter = (
error: WorkspaceMigrationRunnerException,
) => {
+ if (
+ error.code ===
+ WorkspaceMigrationRunnerExceptionCode.DEFERRED_WORKSPACE_MIGRATION_ACTIONS_IN_PROGRESS
+ ) {
+ throw new ConflictError(error.message, {
+ subCode: error.code,
+ userFriendlyMessage: error.userFriendlyMessage,
+ });
+ }
+
const isExecutionFailed =
error.code === WorkspaceMigrationRunnerExceptionCode.EXECUTION_FAILED;