docs: note that onCancel only runs during active execution (triggerdotdev#3119)

isshaddad · web-flow · commit b60788df82d3 · 2026-02-23T21:24:38.000Z
Adds a warning to the onCancel docs clarifying that the hook only fires
when a run is actively executing
diff --git a/docs/tasks/overview.mdx b/docs/tasks/overview.mdx
@@ -535,6 +535,13 @@ export const cancelExampleTask = task({
   point the process will be killed.
 </Note>
 
+<Warning>
+  `onCancel` only runs if the run is actively executing. If a run is cancelled while queued or
+  suspended (e.g. waiting for a token), no machine is spun up and `onCancel` will not be called.
+  This is a known limitation we're planning to address. Follow the progress on our [feedback
+  board](https://feedback.trigger.dev/p/call-the-onfailure-hook-for-runs-that-were-canceled-expired).
+</Warning>
+
 ### `onStart` function (deprecated)
 
 <Info>The `onStart` function was deprecated in v4.1.0. Use `onStartAttempt` instead.</Info>
