fix(webapp,run-engine,core): drop the hidden debounce ceiling, fail fast on an unusable maxDelay

The engine applied a server-side ceiling on how long a debounced run
could be pushed back, defaulting to an hour and documented nowhere. Any
delay at or above it could never push its run, so every trigger created
its own run with no error and nothing on the run to show the debounce
key had been ignored.

The ceiling is now unset by default, so a key keeps collapsing triggers
for as long as they arrive and maxDelay is the only bound. Self-hosters
can still set one. Callers who pass a maxDelay that is not longer than
their delay hit the same dead end, so that pair is rejected at trigger
time rather than silently doing nothing.

Author: matt-aitken

.changeset/debounce-max-duration.md

@@ -2,16 +2,16 @@
 "@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.
+Debouncing with a `delay` longer than an hour now works. A hidden server-side limit was releasing debounced runs after an hour, so any `delay` at or above that never got to push its run back at all: every trigger created its own run, with no error and nothing on the run to show the debounce key had been ignored.
 
-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.
+That limit is gone. A debounce key with no `maxDelay` now keeps pushing its run back for as long as triggers keep arriving, which means it never executes while they do. Set `maxDelay` when the work has to happen eventually, and keep `delay` well below it, since the room available to push is the gap between the two.
 
 ```ts
 await myTask.trigger(payload, {
   debounce: {
     key: "conversation-123",
-    delay: "12h",
-    maxDelay: "36h",
+    delay: "10s",
+    maxDelay: "5m",
   },
 });
 ```

apps/webapp/app/env.server.ts

@@ -1035,17 +1035,13 @@ const EnvironmentSchema = z
     RUN_ENGINE_SUSPENDED_HEARTBEAT_RETRIES_FACTOR: z.coerce.number().default(2),
 
     /**
-     * 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)
+     * Optional ceiling on how long a debounced run can be pushed back, measured from the first
+     * trigger. Unset by default: a continuously triggered debounce key is pushed back for as
+     * long as the triggers keep coming, and `debounce.maxDelay` on the trigger is the only
+     * bound. Setting this applies a ceiling to every debounced run that does not carry its own
+     * `maxDelay`, and any `delay` at or above it stops runs from being pushed at all.
      */
-    RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS: z.coerce
-      .number()
-      .int()
-      .default(24 * 60 * 60 * 1000),
+    RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS: z.coerce.number().int().optional(),
 
     /**
      * Bucket size in milliseconds used to quantize the newly computed `delayUntil`

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

@@ -7,7 +7,6 @@ import type { Tracer } from "@opentelemetry/api";
 import { tryCatch } from "@trigger.dev/core/utils";
 import {
   type TriggerTaskRequestBody,
-  formatDurationMilliseconds,
   RunAnnotations,
   TaskRunError,
   taskRunErrorEnhancer,
@@ -91,7 +90,6 @@ 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
@@ -111,7 +109,6 @@ export class RunEngineTriggerTaskService {
     traceEventConcern: TraceEventConcern;
     tracer: Tracer;
     metadataMaximumSize: number;
-    maximumDebounceDurationMs?: number;
     triggerRacepointSystem?: TriggerRacepointSystem;
     evaluateGate?: MollifierEvaluateGate;
     getMollifierBuffer?: MollifierGetBuffer;
@@ -126,8 +123,6 @@ 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;
@@ -136,63 +131,37 @@ export class RunEngineTriggerTaskService {
   }
 
   /**
-   * 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`.
+   * A debounced run is only pushed back while its new execution time stays inside `maxDelay`,
+   * so the room available to push is `maxDelay` minus `delay`. When a caller sets both and
+   * leaves no room, the debounce key silently does nothing and every trigger creates its own
+   * run, which is worse than being told. Only an explicit `maxDelay` is checked; with no
+   * `maxDelay` there is no ceiling to conflict with.
    */
-  #validateDebounceWindow(
+  #validateDebounceMaxDelay(
     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`
-      );
+    if (!debounce.maxDelay) {
+      return;
     }
 
-    const maxDelayMs = debounce.maxDelay
-      ? parseNaturalLanguageDurationInMs(debounce.maxDelay)
-      : undefined;
+    const maxDelayMs = parseNaturalLanguageDurationInMs(debounce.maxDelay);
 
-    if (debounce.maxDelay && maxDelayMs === undefined) {
+    if (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" });
+    const delayMs = parseNaturalLanguageDurationInMs(debounce.delay);
 
-    if (maxDelayMs !== undefined) {
+    if (delayMs !== undefined && maxDelayMs <= delayMs) {
       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.`
+        `debounce.maxDelay (${debounce.maxDelay}) must be longer than debounce.delay (${debounce.delay}). ` +
+          `A debounced run is only pushed back while it stays inside maxDelay, so with these values ` +
+          `every trigger would create its own run.`
       );
     }
-
-    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
@@ -341,7 +310,7 @@ export class RunEngineTriggerTaskService {
               );
             }
 
-            this.#validateDebounceWindow(body.options.debounce);
+            this.#validateDebounceMaxDelay(body.options.debounce);
           }
 
           const parentRun = body.options?.parentRunId

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

@@ -461,7 +461,7 @@ describe("RunEngineTriggerTaskService", () => {
   });
 
   containerTest(
-    "should reject a debounce window that leaves no room to extend the run",
+    "should reject a debounce maxDelay that leaves no room to push the run back",
     async ({ prisma, redisOptions }) => {
       const engine = new RunEngine({
         prisma,
@@ -515,7 +515,6 @@ describe("RunEngineTriggerTaskService", () => {
         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 }) =>
@@ -525,31 +524,27 @@ describe("RunEngineTriggerTaskService", () => {
           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/);
+        triggerWithDebounce({ key: "equal", delay: "12h", maxDelay: "12h" })
+      ).rejects.toThrow(/must be longer than debounce.delay/);
 
       await expect(
-        triggerWithDebounce({ key: "date-not-duration", delay: "2027-01-01T00:00:00.000Z" })
-      ).rejects.toThrow(/must be a duration, not a date/);
+        triggerWithDebounce({ key: "shorter", delay: "12h", maxDelay: "1h" })
+      ).rejects.toThrow(/must be longer than debounce.delay/);
 
-      const belowCeiling = await triggerWithDebounce({ key: "below-the-ceiling", delay: "12h" });
-      expect(belowCeiling?.run.friendlyId).toBeDefined();
+      await expect(
+        triggerWithDebounce({ key: "unparseable", delay: "10s", maxDelay: "soon" })
+      ).rejects.toThrow(/Invalid debounce maxDelay/);
 
-      const raisedCeiling = await triggerWithDebounce({
-        key: "raised-ceiling",
-        delay: "36h",
-        maxDelay: "72h",
+      const withRoom = await triggerWithDebounce({
+        key: "with-room",
+        delay: "10s",
+        maxDelay: "5m",
       });
-      expect(raisedCeiling?.run.friendlyId).toBeDefined();
+      expect(withRoom?.run.friendlyId).toBeDefined();
+
+      const noMaxDelay = await triggerWithDebounce({ key: "no-max-delay", delay: "12h" });
+      expect(noMaxDelay?.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`. Defaults to the maximum debounce duration, which is 24 hours on Trigger.dev Cloud
+- `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute. Uses the same duration format as `delay`. Not set by default
 
 **How it works:**
 
@@ -882,38 +882,11 @@ 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.
+  There is no time limit on step 2. While triggers keep arriving on the same key, the run keeps
+  being pushed back and never executes. A key triggered every 10 seconds with a `delay` of `"30s"`
+  runs 30 seconds after the triggers stop, however long that takes. Set `maxDelay` whenever the
+  work needs to happen eventually.
 </Warning>
 
 **Limiting total delay with `maxDelay`:**
@@ -955,6 +928,8 @@ Consider `delay: "5s"` and `maxDelay: "30s"` with triggers arriving every 2 seco
 
 Without `maxDelay`, continuous triggers would prevent the run from ever executing. With `maxDelay: "30s"`, execution is guaranteed within 30 seconds of the first trigger.
 
+Keep `delay` well below `maxDelay`. A run is only pushed back while its new execution time stays inside `maxDelay`, so the room you have to push is `maxDelay` minus `delay`. Setting them equal, or setting `delay` higher, leaves no room at all: every trigger creates its own run and the debounce key has no effect.
+
 <Note>
   The `maxDelay` value is evaluated from each trigger call, not stored with the original run. This
   means if you pass different `maxDelay` values for the same debounce key, each trigger uses its own

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 ?? 24 * 60 * 60 * 1000,
+      maxDebounceDurationMs: options.debounce?.maxDebounceDurationMs,
       quantizeNewDelayUntilMs: options.debounce?.quantizeNewDelayUntilMs ?? 1000,
       fastPathSkipEnabled: options.debounce?.fastPathSkipEnabled ?? true,
       useReplicaForFastPathRead: options.debounce?.useReplicaForFastPathRead ?? false,