From b60788df82d3d55f127d72215c6de7d1b94379f0 Mon Sep 17 00:00:00 2001
From: Iss <74388823+isshaddad@users.noreply.github.com>
Date: Mon, 23 Feb 2026 16:24:38 -0500
Subject: [PATCH] docs: note that onCancel only runs during active execution
 (#3119)

Adds a warning to the onCancel docs clarifying that the hook only fires
when a run is actively executing
---
 docs/tasks/overview.mdx | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/tasks/overview.mdx b/docs/tasks/overview.mdx
index fe2e7ce5c..b2bca9bc1 100644
--- 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>