fix(webapp,run-engine,core): raise the debounce ceiling to 24h and reject windows that cannot debounce

A debounced run is only pushed later while the new execution time stays
inside maxDelay (or the server maximum) measured from the first trigger,
so the room to push is the gap between the two. A delay at or above that
ceiling meant the first extension was already out of bounds: every
trigger created its own run, with no error and nothing on the run to
show the debounce had been ignored.

The default ceiling moves from 1 hour to 24 hours, and a delay that
leaves no room is now rejected at trigger time with a message naming
both values and how to fix them. debounce.delay must also be a duration
rather than a date, since it is re-applied on every extension.

Author: matt-aitken

.changeset/debounce-max-duration.md

@@ -0,0 +1,17 @@
+---
+"@trigger.dev/core": patch
+---
+
+Debounce windows can now run up to 24 hours by default, and a `debounce.delay` that leaves no room to extend the run is rejected instead of silently doing nothing.
+
+A debounced run is only pushed later while its new execution time stays inside `maxDelay` (or the server maximum) measured from the first trigger, so the room you have to push is `maxDelay` minus `delay`. Setting a `delay` at or above that ceiling previously meant every trigger created its own run, with no error and nothing on the run to show the debounce had been ignored. Those triggers now fail with a message naming both values and how to fix them.
+
+```ts
+await myTask.trigger(payload, {
+  debounce: {
+    key: "conversation-123",
+    delay: "12h",
+    maxDelay: "36h",
+  },
+});
+```

apps/webapp/app/env.server.ts

@@ -1034,11 +1034,18 @@ const EnvironmentSchema = z
       .default(60_000),
     RUN_ENGINE_SUSPENDED_HEARTBEAT_RETRIES_FACTOR: z.coerce.number().default(2),
 
-    /** Maximum duration in milliseconds that a run can be debounced. Default: 1 hour (3,600,000ms) */
+    /**
+     * Ceiling on how long a debounced run can be pushed back, measured from the first trigger.
+     * Acts as the default when a trigger does not set `debounce.maxDelay`; a trigger that does
+     * set it overrides this entirely. A `debounce.delay` at or above the effective ceiling is
+     * rejected at trigger time, since no trigger could ever extend the run.
+     *
+     * Default: 24 hours (86,400,000ms)
+     */
     RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS: z.coerce
       .number()
       .int()
-      .default(60_000 * 60), // 1 hour
+      .default(24 * 60 * 60 * 1000),
 
     /**
      * Bucket size in milliseconds used to quantize the newly computed `delayUntil`

apps/webapp/app/runEngine/services/triggerTask.server.ts

@@ -7,13 +7,15 @@ import type { Tracer } from "@opentelemetry/api";
 import { tryCatch } from "@trigger.dev/core/utils";
 import {
   type TriggerTaskRequestBody,
+  formatDurationMilliseconds,
   RunAnnotations,
   TaskRunError,
   taskRunErrorEnhancer,
   taskRunErrorToString,
   TriggerTraceContext,
 } from "@trigger.dev/core/v3";
 import {
+  parseNaturalLanguageDurationInMs,
   parseTraceparent,
   RunId,
   serializeTraceparent,
@@ -89,6 +91,7 @@ export class RunEngineTriggerTaskService {
   private readonly traceEventConcern: TraceEventConcern;
   private readonly triggerRacepointSystem: TriggerRacepointSystem;
   private readonly metadataMaximumSize: number;
+  private readonly maximumDebounceDurationMs: number;
   // Mollifier hooks are DI'd so tests can drive the call-site's mollify branch
   // deterministically (stub the gate to return mollify, inject a real or fake
   // buffer, force the global-enabled predicate to true so the call site
@@ -108,6 +111,7 @@ export class RunEngineTriggerTaskService {
     traceEventConcern: TraceEventConcern;
     tracer: Tracer;
     metadataMaximumSize: number;
+    maximumDebounceDurationMs?: number;
     triggerRacepointSystem?: TriggerRacepointSystem;
     evaluateGate?: MollifierEvaluateGate;
     getMollifierBuffer?: MollifierGetBuffer;
@@ -122,13 +126,75 @@ export class RunEngineTriggerTaskService {
     this.tracer = opts.tracer;
     this.traceEventConcern = opts.traceEventConcern;
     this.metadataMaximumSize = opts.metadataMaximumSize;
+    this.maximumDebounceDurationMs =
+      opts.maximumDebounceDurationMs ?? env.RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS;
     this.triggerRacepointSystem = opts.triggerRacepointSystem ?? new NoopTriggerRacepointSystem();
     this.evaluateGate = opts.evaluateGate ?? defaultEvaluateGate;
     this.getMollifierBuffer = opts.getMollifierBuffer ?? defaultGetMollifierBuffer;
     this.isMollifierGloballyEnabled =
       opts.isMollifierGloballyEnabled ?? (() => env.TRIGGER_MOLLIFIER_ENABLED === "1");
   }
 
+  /**
+   * Rejects debounce settings that can never debounce anything.
+   *
+   * A trigger extends an existing debounced run by moving its `delayUntil` to `now + delay`,
+   * and that is only allowed while the new time stays inside `createdAt + ceiling`, where the
+   * ceiling is the trigger's own `maxDelay` or the server default. So a `delay` at or above the
+   * ceiling means the very first extension is already out of bounds: every trigger starts its
+   * own run and the debounce key does nothing. The usable window for extensions is
+   * `ceiling - delay`.
+   */
+  #validateDebounceWindow(
+    debounce: NonNullable<NonNullable<TriggerTaskRequestBody["options"]>["debounce"]>
+  ) {
+    const delayMs = parseNaturalLanguageDurationInMs(debounce.delay);
+
+    if (delayMs === undefined) {
+      throw new ServiceValidationError(
+        `Invalid debounce delay: ${debounce.delay}. ` +
+          `debounce.delay must be a duration, not a date. ` +
+          `Supported formats: {number}s, {number}m, {number}h, {number}d, {number}w`
+      );
+    }
+
+    const maxDelayMs = debounce.maxDelay
+      ? parseNaturalLanguageDurationInMs(debounce.maxDelay)
+      : undefined;
+
+    if (debounce.maxDelay && maxDelayMs === undefined) {
+      throw new ServiceValidationError(
+        `Invalid debounce maxDelay: ${debounce.maxDelay}. ` +
+          `Supported formats: {number}s, {number}m, {number}h, {number}d, {number}w`
+      );
+    }
+
+    const ceilingMs = maxDelayMs ?? this.maximumDebounceDurationMs;
+
+    if (delayMs < ceilingMs) {
+      return;
+    }
+
+    const delayText = formatDurationMilliseconds(delayMs, { style: "short" });
+    const ceilingText = formatDurationMilliseconds(ceilingMs, { style: "short" });
+
+    if (maxDelayMs !== undefined) {
+      throw new ServiceValidationError(
+        `debounce.delay (${delayText}) must be shorter than debounce.maxDelay (${ceilingText}). ` +
+          `A debounced run can only be extended while it is inside the maxDelay window, so with ` +
+          `these values every trigger would create its own run. Raise maxDelay above the delay ` +
+          `to give yourself an extension window of maxDelay minus delay.`
+      );
+    }
+
+    throw new ServiceValidationError(
+      `debounce.delay (${delayText}) is at or above the maximum debounce duration of ${ceilingText}. ` +
+        `A debounced run can only be extended while it is inside that window, so with this delay ` +
+        `every trigger would create its own run. Either shorten the delay, or set ` +
+        `debounce.maxDelay above ${delayText} to raise the ceiling for this trigger.`
+    );
+  }
+
   // Mint a new run's friendlyId. The id-kind decides which store the run is born
   // in (cuid → legacy store, run-ops id → new store), so the whole subgraph of a run
   // must agree. Two cases:
@@ -274,6 +340,8 @@ export class RunEngineTriggerTaskService {
                   `Supported formats: {number}s, {number}m, {number}h, {number}d, {number}w`
               );
             }
+
+            this.#validateDebounceWindow(body.options.debounce);
           }
 
           const parentRun = body.options?.parentRunId

apps/webapp/test/engine/triggerTask.debounce.test.ts

@@ -459,4 +459,97 @@ describe("RunEngineTriggerTaskService", () => {
     expect(result).toBeDefined();
     expect(result?.run.friendlyId).toBeDefined();
   });
+
+  containerTest(
+    "should reject a debounce window that leaves no room to extend the run",
+    async ({ prisma, redisOptions }) => {
+      const engine = new RunEngine({
+        prisma,
+        worker: {
+          redis: redisOptions,
+          workers: 1,
+          tasksPerWorker: 10,
+          pollIntervalMs: 100,
+        },
+        queue: {
+          redis: redisOptions,
+        },
+        runLock: {
+          redis: redisOptions,
+        },
+        machines: {
+          defaultMachine: "small-1x",
+          machines: {
+            "small-1x": {
+              name: "small-1x" as const,
+              cpu: 0.5,
+              memory: 0.5,
+              centsPerMs: 0.0001,
+            },
+          },
+          baseCostInCents: 0.0005,
+        },
+        tracer: trace.getTracer("test", "0.0.0"),
+      });
+      onTestFinished(() => engine.quit());
+
+      const authenticatedEnvironment = await setupAuthenticatedEnvironment(prisma, "PRODUCTION");
+      const taskIdentifier = "test-task";
+
+      await setupBackgroundWorker(engine, authenticatedEnvironment, taskIdentifier);
+
+      const queuesManager = new DefaultQueueManager(prisma, engine);
+      const idempotencyKeyConcern = new IdempotencyKeyConcern(
+        prisma,
+        engine,
+        new MockTraceEventConcern()
+      );
+
+      const triggerTaskService = new RunEngineTriggerTaskService({
+        engine,
+        prisma,
+        payloadProcessor: new MockPayloadProcessor(),
+        queueConcern: queuesManager,
+        idempotencyKeyConcern,
+        validator: new MockTriggerTaskValidator(),
+        traceEventConcern: new MockTraceEventConcern(),
+        tracer: trace.getTracer("test", "0.0.0"),
+        metadataMaximumSize: 1024 * 1024 * 1,
+        maximumDebounceDurationMs: 24 * 60 * 60 * 1000,
+      });
+
+      const triggerWithDebounce = (debounce: { key: string; delay: string; maxDelay?: string }) =>
+        triggerTaskService.call({
+          taskId: taskIdentifier,
+          environment: authenticatedEnvironment,
+          body: { payload: { test: "test" }, options: { debounce } },
+        });
+
+      await expect(triggerWithDebounce({ key: "at-the-ceiling", delay: "24h" })).rejects.toThrow(
+        /at or above the maximum debounce duration/
+      );
+
+      await expect(triggerWithDebounce({ key: "above-the-ceiling", delay: "48h" })).rejects.toThrow(
+        /at or above the maximum debounce duration/
+      );
+
+      await expect(
+        triggerWithDebounce({ key: "delay-equals-max", delay: "12h", maxDelay: "12h" })
+      ).rejects.toThrow(/must be shorter than debounce.maxDelay/);
+
+      await expect(
+        triggerWithDebounce({ key: "date-not-duration", delay: "2027-01-01T00:00:00.000Z" })
+      ).rejects.toThrow(/must be a duration, not a date/);
+
+      const belowCeiling = await triggerWithDebounce({ key: "below-the-ceiling", delay: "12h" });
+      expect(belowCeiling?.run.friendlyId).toBeDefined();
+
+      const raisedCeiling = await triggerWithDebounce({
+        key: "raised-ceiling",
+        delay: "36h",
+        maxDelay: "72h",
+      });
+      expect(raisedCeiling?.run.friendlyId).toBeDefined();
+    }
+  );
 });

docs/triggering.mdx

@@ -873,7 +873,7 @@ The `debounce` option accepts:
 - `key` - A unique string to identify the debounce group (scoped to the task)
 - `delay` - Duration string specifying how long to delay. Supported units: `s` (seconds), `m` (minutes), `h`/`hr` (hours), `d` (days), `w` (weeks). Minimum is 1 second. Examples: `"5s"`, `"1m"`, `"2h30m"`
 - `mode` - Optional. Controls which trigger's data is used: `"leading"` (default) or `"trailing"`
-- `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute. Uses the same duration format as `delay`
+- `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute. Uses the same duration format as `delay`. Defaults to the maximum debounce duration, which is 24 hours on Trigger.dev Cloud
 
 **How it works:**
 
@@ -882,9 +882,43 @@ The `debounce` option accepts:
 3. Once no new triggers occur within the delay duration, the run executes
 4. After the run starts executing, a new trigger with the same key will create a new run
 
+**Your delay must fit inside the maximum:**
+
+A run can only be pushed later while its new execution time stays inside `maxDelay`, measured from the first trigger. The room you have to push is therefore `maxDelay` minus `delay`. With `delay: "5s"` and the 24 hour default, a key can be pushed for almost a full day. With `delay: "24h"` and no `maxDelay`, there is no room at all: the first push is already out of bounds, so every trigger would create its own run.
+
+Triggers like that are rejected rather than silently behaving as if you had not set a debounce:
+
+```
+debounce.delay (24h) is at or above the maximum debounce duration of 1d. A debounced run
+can only be extended while it is inside that window, so with this delay every trigger would
+create its own run. Either shorten the delay, or set debounce.maxDelay above 24h to raise
+the ceiling for this trigger.
+```
+
+To debounce for longer than 24 hours, set `maxDelay` above your `delay`:
+
+```ts
+await myTask.trigger(
+  { conversationId: "123" },
+  {
+    debounce: {
+      key: "conversation-123",
+      delay: "12h",   // Wait 12h after each trigger
+      maxDelay: "36h", // Keep extending for up to 36h from the first trigger
+    },
+  }
+);
+```
+
+<Warning>
+  `delay` must be a duration string, not a date. A date is accepted by the `delay` option on a
+  normal trigger, but `debounce.delay` is re-applied every time the run is pushed later, so it has
+  to be relative.
+</Warning>
+
 **Limiting total delay with `maxDelay`:**
 
-By default, continuous triggers can delay execution indefinitely. The `maxDelay` option sets an upper bound on the total delay from the first trigger, ensuring the run eventually executes even with constant activity.
+The `maxDelay` option sets an upper bound on the total delay from the first trigger, ensuring the run eventually executes even with constant activity.
 
 ```ts
 await summarizeChat.trigger(

internal-packages/run-engine/src/engine/index.ts

@@ -384,7 +384,7 @@ export class RunEngine {
       redis: options.debounce?.redis ?? options.runLock.redis,
       executionSnapshotSystem: this.executionSnapshotSystem,
       delayedRunSystem: this.delayedRunSystem,
-      maxDebounceDurationMs: options.debounce?.maxDebounceDurationMs ?? 60 * 60 * 1000, // Default 1 hour
+      maxDebounceDurationMs: options.debounce?.maxDebounceDurationMs ?? 24 * 60 * 60 * 1000,
       quantizeNewDelayUntilMs: options.debounce?.quantizeNewDelayUntilMs ?? 1000,
       fastPathSkipEnabled: options.debounce?.fastPathSkipEnabled ?? true,
       useReplicaForFastPathRead: options.debounce?.useReplicaForFastPathRead ?? false,

internal-packages/run-engine/src/engine/tests/debounce.test.ts

@@ -3177,4 +3177,81 @@ describe("RunEngine debounce", () => {
       }
     );
   }
+
+  containerTest(
+    "Debounce: a long delay under the default maximum keeps extending one run",
+    async ({ prisma, redisOptions }) => {
+      const authenticatedEnvironment = await setupAuthenticatedEnvironment(prisma, "PRODUCTION");
+
+      const engine = new RunEngine({
+        prisma,
+        worker: {
+          redis: redisOptions,
+          workers: 1,
+          tasksPerWorker: 10,
+          pollIntervalMs: 100,
+        },
+        queue: {
+          redis: redisOptions,
+        },
+        runLock: {
+          redis: redisOptions,
+        },
+        machines: {
+          defaultMachine: "small-1x",
+          machines: {
+            "small-1x": {
+              name: "small-1x" as const,
+              cpu: 0.5,
+              memory: 0.5,
+              centsPerMs: 0.0001,
+            },
+          },
+          baseCostInCents: 0.0001,
+        },
+        tracer: trace.getTracer("test", "0.0.0"),
+      });
+
+      try {
+        const taskIdentifier = "test-task";
+
+        await setupBackgroundWorker(engine, authenticatedEnvironment, taskIdentifier);
+
+        const runIds: string[] = [];
+
+        for (let i = 0; i < 4; i++) {
+          const run = await engine.trigger(
+            {
+              number: i + 1,
+              friendlyId: `run_long${i}`,
+              environment: authenticatedEnvironment,
+              taskIdentifier,
+              payload: `{"data": ${i}}`,
+              payloadType: "application/json",
+              context: {},
+              traceContext: {},
+              traceId: `t1234${i}`,
+              spanId: `s1234${i}`,
+              workerQueue: "main",
+              queue: "task/test-task",
+              isTest: false,
+              tags: [],
+              delayUntil: new Date(Date.now() + 12 * 60 * 60 * 1000),
+              debounce: {
+                key: "user-123",
+                delay: "12h",
+              },
+            },
+            prisma
+          );
+
+          runIds.push(run.id);
+        }
+
+        expect(new Set(runIds).size).toBe(1);
+      } finally {
+        await engine.quit();
+      }
+    }
+  );
 });