triggerdotdev · myftija · May 28, 2026 · May 28, 2026 · devin-ai-integration · May 28, 2026
diff --git a/.server-changes/idempotent-background-worker-registration.md b/.server-changes/idempotent-background-worker-registration.md
@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Make `POST /api/v1/deployments/:deploymentId/background-workers` idempotent (for sequential requests only) so client-side retries no longer collide on the `BackgroundWorker` `(project, env, version)` unique index. Helps make deployments more resilient against the class of indexing failures that surfaces in the dashboard as "Indexing timed out", e.g. during transient database issues.
diff --git a/apps/webapp/app/v3/services/createBackgroundWorker.server.ts b/apps/webapp/app/v3/services/createBackgroundWorker.server.ts
@@ -34,31 +34,8 @@ import { tryCatch } from "@trigger.dev/core/v3";
 import { engine } from "../runEngine.server";
 import { scheduleEngine } from "../scheduleEngine.server";
 
-/**
- * Strip BackgroundWorkerMetadata down to the slice that's actually read after
- * storage. Everything else is duplicated to dedicated columns/tables
- * (BackgroundWorker.{contentHash,cliVersion,sdkVersion,runtime,runtimeVersion},
- * BackgroundWorkerTask, BackgroundWorkerFile, TaskQueue, Prompt). Today the
- * only post-write reader is changeCurrentDeployment.server.ts, which feeds
- * tasks[].schedule into syncDeclarativeSchedules. packageVersion, contentHash,
- * and tasks[].filePath are kept solely to satisfy BackgroundWorkerMetadata's
- * required fields when the column is parsed back.
- */
-export function stripBackgroundWorkerMetadataForStorage(
-  metadata: BackgroundWorkerMetadata
-): Prisma.InputJsonValue {
-  return {
-    packageVersion: metadata.packageVersion,
-    contentHash: metadata.contentHash,
-    tasks: metadata.tasks
-      .filter((t) => t.schedule)
-      .map((t) => ({
-        id: t.id,
-        filePath: t.filePath,
-        schedule: t.schedule,
-      })),
-  };
-}
+import { stripBackgroundWorkerMetadataForStorage } from "./stripBackgroundWorkerMetadataForStorage.server";
+export { stripBackgroundWorkerMetadataForStorage };
 
 export class CreateBackgroundWorkerService extends BaseService {
   private readonly _taskMetaCache: TaskMetadataCache;
@@ -356,8 +333,13 @@ async function createWorkerTask(
   prisma: PrismaClientOrTransaction,
   tasksToBackgroundFiles?: Map<string, string>
 ): Promise<TaskMetadataEntry | null> {
+  // Hoisted so the P2002 catch branch can return the same entry shape.
+  let queue: TaskQueue | undefined;
+  let resolvedTriggerSource: "SCHEDULED" | "AGENT" | "STANDARD" | undefined;
+  let resolvedTtl: string | null | undefined;
+
   try {
-    let queue = queues.find((queue) => queue.name === task.queue?.name);
+    queue = queues.find((queue) => queue.name === task.queue?.name);
 
     if (!queue) {
       // Create a TaskQueue
@@ -374,14 +356,14 @@ async function createWorkerTask(
       );
     }
 
-    const resolvedTriggerSource =
+    resolvedTriggerSource =
       task.triggerSource === "schedule"
         ? ("SCHEDULED" as const)
         : task.triggerSource === "agent"
           ? ("AGENT" as const)
           : ("STANDARD" as const);
 
-    const resolvedTtl =
+    resolvedTtl =
       typeof task.ttl === "number" ? stringifyDuration(task.ttl) ?? null : task.ttl ?? null;
 
     await prisma.backgroundWorkerTask.create({
@@ -418,10 +400,26 @@ async function createWorkerTask(
     if (error instanceof Prisma.PrismaClientKnownRequestError) {
       // The error code for unique constraint violation in Prisma is P2002
       if (error.code === "P2002") {
-        logger.warn("Task already exists", {
+        // Retry landing after the first attempt's row was already written.
+        const existing = await prisma.backgroundWorkerTask.findFirst({
+          where: { workerId: worker.id, slug: task.id },
+          select: { id: true },
+        });
+
+        logger.warn("Attempted to recreate background worker task", {
           task,
           worker,
         });
+
+        if (existing && queue && resolvedTriggerSource && resolvedTtl !== undefined) {
+          return {
+            slug: task.id,
+            ttl: resolvedTtl,
+            triggerSource: resolvedTriggerSource,
+            queueId: queue.id,
+            queueName: queue.name,
+          };
+        }
       } else {
         logger.error("Prisma Error creating background worker task", {
           error: {

diff --git a/apps/webapp/app/v3/services/createDeploymentBackgroundWorkerV4.server.ts b/apps/webapp/app/v3/services/createDeploymentBackgroundWorkerV4.server.ts
@@ -1,16 +1,19 @@
 import { CreateBackgroundWorkerRequestBody, logger, tryCatch } from "@trigger.dev/core/v3";
-import { BackgroundWorkerId } from "@trigger.dev/core/v3/isomorphic";
-import type { BackgroundWorker, PrismaClientOrTransaction, WorkerDeployment } from "@trigger.dev/database";
+import type {
+  BackgroundWorker,
+  PrismaClientOrTransaction,
+  WorkerDeployment,
+} from "@trigger.dev/database";
 import { AuthenticatedEnvironment } from "~/services/apiAuth.server";
 import { type TaskMetadataCache } from "~/services/taskMetadataCache.server";
 import { taskMetadataCacheInstance } from "~/services/taskMetadataCacheInstance.server";
 import { BaseService, ServiceValidationError } from "./baseService.server";
 import {
   createBackgroundFiles,
   createWorkerResources,
-  stripBackgroundWorkerMetadataForStorage,
   syncDeclarativeSchedules,
 } from "./createBackgroundWorker.server";
+import { findOrCreateBackgroundWorker } from "./createDeploymentBackgroundWorkerV4/findOrCreateBackgroundWorker.server";
 import { TimeoutDeploymentService } from "./timeoutDeployment.server";
 import { env } from "~/env.server";
 
@@ -50,6 +53,11 @@ export class CreateDeploymentBackgroundWorkerServiceV4 extends BaseService {
       });
 
       if (!deployment) {
+        logger.warn("createDeploymentBackgroundWorker: deployment not found", {
+          deploymentId,
+          environmentId: environment.id,
+          projectId: environment.projectId,
+        });
         return;
       }
 
@@ -70,25 +78,21 @@ export class CreateDeploymentBackgroundWorkerServiceV4 extends BaseService {
       }
 
       if (deployment.status !== "BUILDING") {
+        logger.warn("createDeploymentBackgroundWorker: deployment not in BUILDING state", {
+          deploymentId,
+          deploymentStatus: deployment.status,
+          environmentId: environment.id,
+          projectId: environment.projectId,
+        });
         return;
       }
 
-      const backgroundWorker = await this._prisma.backgroundWorker.create({
-        data: {
-          ...BackgroundWorkerId.generate(),
-          version: deployment.version,
-          runtimeEnvironmentId: environment.id,
-          projectId: environment.projectId,
-          metadata: stripBackgroundWorkerMetadataForStorage(body.metadata),
-          contentHash: body.metadata.contentHash,
-          cliVersion: body.metadata.cliPackageVersion,
-          sdkVersion: body.metadata.packageVersion,
-          supportsLazyAttempts: body.supportsLazyAttempts,
-          engine: body.engine,
-          runtime: body.metadata.runtime,
-          runtimeVersion: body.metadata.runtimeVersion,
-        },
-      });
+      const backgroundWorker = await findOrCreateBackgroundWorker(
+        environment,
+        deployment,
+        body,
+        this._prisma
+      );
 
       //upgrade the project to engine "V2" if it's not already
       if (environment.project.engine === "V1" && body.engine === "V2") {
@@ -188,10 +192,11 @@ export class CreateDeploymentBackgroundWorkerServiceV4 extends BaseService {
         throw serviceError;
       }
 
-      // Link the deployment with the background worker
-      await this._prisma.workerDeployment.update({
+      // Guarded BUILDING → DEPLOYING transition. `updateMany` for optimistic concurrency control
+      const { count: updatedCount } = await this._prisma.workerDeployment.updateMany({
         where: {
           id: deployment.id,
+          status: "BUILDING",
         },
         data: {
           status: "DEPLOYING",
@@ -203,6 +208,18 @@ export class CreateDeploymentBackgroundWorkerServiceV4 extends BaseService {
         },
       });
 
+      if (updatedCount === 0) {
+        logger.warn(
+          "createDeploymentBackgroundWorker: deployment no longer in BUILDING state, skipping DEPLOYING transition",
+          {
+            deploymentId,
+            environmentId: environment.id,
+            projectId: environment.projectId,
+          }
+        );
+        return backgroundWorker;
+      }
+
       await TimeoutDeploymentService.enqueue(
         deployment.id,
         "DEPLOYING",

diff --git a/...app/v3/services/createDeploymentBackgroundWorkerV4/findOrCreateBackgroundWorker.server.ts b/...app/v3/services/createDeploymentBackgroundWorkerV4/findOrCreateBackgroundWorker.server.ts
@@ -0,0 +1,56 @@
+import type { CreateBackgroundWorkerRequestBody } from "@trigger.dev/core/v3";
+import { BackgroundWorkerId } from "@trigger.dev/core/v3/isomorphic";
+import type {
+  BackgroundWorker,
+  PrismaClientOrTransaction,
+  WorkerDeployment,
+} from "@trigger.dev/database";
+import type { AuthenticatedEnvironment } from "~/services/apiAuth.server";
+import { ServiceValidationError } from "../common.server";
+import { stripBackgroundWorkerMetadataForStorage } from "../stripBackgroundWorkerMetadataForStorage.server";
+
+/**
+ * Idempotent on `(project, environment, version)` for sequential calls, not concurrent calls.
+ */
+export async function findOrCreateBackgroundWorker(
+  environment: AuthenticatedEnvironment,
+  deployment: WorkerDeployment,
+  body: CreateBackgroundWorkerRequestBody,
+  prisma: PrismaClientOrTransaction
+): Promise<BackgroundWorker> {
+  const existing = await prisma.backgroundWorker.findFirst({
+    where: {
+      projectId: environment.projectId,
+      runtimeEnvironmentId: environment.id,
+      version: deployment.version,
+    },
+  });
+
+  if (existing && existing.contentHash === body.metadata.contentHash) {
+    return existing;
+  }
+
+  if (existing) {
+    throw new ServiceValidationError(
+      "A background worker for this deployment version already exists with a different content hash",
+      409
+    );
+  }
+
+  return prisma.backgroundWorker.create({
+    data: {
+      ...BackgroundWorkerId.generate(),
+      version: deployment.version,
+      runtimeEnvironmentId: environment.id,
+      projectId: environment.projectId,
+      metadata: stripBackgroundWorkerMetadataForStorage(body.metadata),
+      contentHash: body.metadata.contentHash,
+      cliVersion: body.metadata.cliPackageVersion,
+      sdkVersion: body.metadata.packageVersion,
+      supportsLazyAttempts: body.supportsLazyAttempts,
+      engine: body.engine,
+      runtime: body.metadata.runtime,
+      runtimeVersion: body.metadata.runtimeVersion,
+    },
+  });
+}
diff --git a/apps/webapp/app/v3/services/stripBackgroundWorkerMetadataForStorage.server.ts b/apps/webapp/app/v3/services/stripBackgroundWorkerMetadataForStorage.server.ts
@@ -0,0 +1,28 @@
+import { BackgroundWorkerMetadata } from "@trigger.dev/core/v3";
+import { Prisma } from "@trigger.dev/database";
+
+/**
+ * Strip BackgroundWorkerMetadata down to the slice that's actually read after
+ * storage. Everything else is duplicated to dedicated columns/tables
+ * (BackgroundWorker.{contentHash,cliVersion,sdkVersion,runtime,runtimeVersion},
+ * BackgroundWorkerTask, BackgroundWorkerFile, TaskQueue, Prompt). Today the
+ * only post-write reader is changeCurrentDeployment.server.ts, which feeds
+ * tasks[].schedule into syncDeclarativeSchedules. packageVersion, contentHash,
+ * and tasks[].filePath are kept solely to satisfy BackgroundWorkerMetadata's
+ * required fields when the column is parsed back.
+ */
+export function stripBackgroundWorkerMetadataForStorage(
+  metadata: BackgroundWorkerMetadata
+): Prisma.InputJsonValue {
+  return {
+    packageVersion: metadata.packageVersion,
+    contentHash: metadata.contentHash,
+    tasks: metadata.tasks
+      .filter((t) => t.schedule)
+      .map((t) => ({
+        id: t.id,
+        filePath: t.filePath,
+        schedule: t.schedule,
+      })),
+  };
+}