Temporal Ts Cancellation

1. Where is Temporal running?

   • Local dev server (localhost:7233)
   • Self-hosted (get full address, e.g. temporal.example.com:7233)
   • Temporal Cloud (get namespace and address)

2. What is the full Temporal gRPC address? (if not local)

3. Is there ingress set up for the Temporal HTTP API?

   • If yes, get the full URL (e.g. https://flow.remodl.ai:443)
   • If no, note that only gRPC client connections and CLI with --address will work

4. What namespace are they using? (default: "default")

Use these answers to configure all connection and CLI snippets.

Overview

Temporal TypeScript workflows use a tree of CancellationScopes to manage cancellation. Every workflow runs in a root scope. You create child scopes to control which operations get cancelled and which are shielded. Cancellation propagates from outer scopes to inner scopes. You handle cancellation by catching CancelledFailure errors.

This skill covers:

• Creating and nesting cancellation scopes
• Shielding cleanup logic from cancellation
• Setting timeouts on groups of operations
• Cancelling activities via heartbeats
• Resetting stuck workflow executions

Quick Reference

What Gets Cancelled

When a CancellationScope is cancelled, these operations inside it are cancelled:

• Activities (proxied via proxyActivities)
• Timers (created with sleep())
• Triggers (new Trigger())
• Child Workflows

Cancellation propagates to nested cancellable child scopes.

Error Types on Cancellation

Always use isCancellation(err) for a unified check -- it handles all wrapper types.

Implementation Patterns

Pattern 1: Internal Cancellation (cancel a timer or activity programmatically)

import { CancellationScope, CancelledFailure, sleep } from '@temporalio/workflow';

export async function cancelTimerExample(): Promise<void> {
  try {
    await CancellationScope.cancellable(async () => {
      const promise = sleep(60_000);
      CancellationScope.current().cancel(); // cancel immediately
      await promise; // must await for CancelledFailure to throw
    });
  } catch (e) {
    if (e instanceof CancelledFailure) {
      // Timer was cancelled -- handle as needed
    } else {
      throw e;
    }
  }
}

Alternative using the constructor:

const scope = new CancellationScope();
const promise = scope.run(() => sleep(60_000));
scope.cancel();
await promise; // throws CancelledFailure

Pattern 2: External Cancellation with Cleanup

When an external client calls handle.cancel(), the workflow's root scope is cancelled. Use nonCancellable to run cleanup:

import { CancellationScope, proxyActivities, isCancellation } from '@temporalio/workflow';
import type * as activities from './activities';

const { processOrder, refundOrder } = proxyActivities<typeof activities>({
  startToCloseTimeout: '10m',
});

export async function orderWorkflow(orderId: string): Promise<void> {
  try {
    await processOrder(orderId);
  } catch (err) {
    if (isCancellation(err)) {
      // MUST use nonCancellable -- root scope is already cancelled
      await CancellationScope.nonCancellable(() => refundOrder(orderId));
    }
    throw err; // re-throw to mark workflow as cancelled
  }
}

Pattern 3: Timeout on a Group of Activities

import { CancellationScope, proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { fetchData } = proxyActivities<typeof activities>({
  startToCloseTimeout: '30s',
});

export async function fetchWithDeadline(urls: string[]): Promise<any[]> {
  // All activities cancelled if total time exceeds 60s
  return CancellationScope.withTimeout(
    60_000,
    () => Promise.all(urls.map((url) => fetchData(url)))
  );
}

Pattern 4: Shield an Operation from Cancellation

import { CancellationScope, proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { criticalWrite } = proxyActivities<typeof activities>({
  startToCloseTimeout: '5m',
});

export async function shieldedWorkflow(data: any): Promise<void> {
  // This activity will complete even if the workflow is cancelled
  await CancellationScope.nonCancellable(() => criticalWrite(data));
}

Pattern 5: Race Cancellation Against a nonCancellable Operation

Use cancelRequested to detect cancellation while waiting on a shielded operation:

import { CancellationScope, CancelledFailure, proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { longRunningTask } = proxyActivities<typeof activities>({
  startToCloseTimeout: '10m',
});

export async function raceExample(input: string): Promise<any> {
  let result: any;
  const scope = new CancellationScope({ cancellable: false });
  const promise = scope.run(() => longRunningTask(input));

  try {
    result = await Promise.race([scope.cancelRequested, promise]);
  } catch (err) {
    if (!(err instanceof CancelledFailure)) throw err;
    // Workflow was cancelled but we still wait for the shielded activity
    result = await promise;
  }
  return result;
}

Pattern 6: Nested Scopes (setup, work with timeout, cleanup)

import { CancellationScope, proxyActivities, isCancellation } from '@temporalio/workflow';
import type * as activities from './activities';

const { setup, doWork, cleanup } = proxyActivities<typeof activities>({
  startToCloseTimeout: '10m',
});

export async function nestedScopeWorkflow(url: string): Promise<void> {
  // Setup is shielded from cancellation
  await CancellationScope.nonCancellable(() => setup());

  try {
    // Work has a 30s deadline
    await CancellationScope.withTimeout(30_000, () => doWork(url));
  } catch (err) {
    if (isCancellation(err)) {
      // Cleanup is shielded from cancellation
      await CancellationScope.nonCancellable(() => cleanup(url));
    }
    throw err;
  }
}

Pattern 7: Sharing Promises Between Scopes

Operations are cancelled by the scope they were created in, not the scope they are awaited in:

import { CancellationScope, proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { fetchData } = proxyActivities<typeof activities>({
  startToCloseTimeout: '5m',
});

export async function sharedPromiseExample(): Promise<any> {
  // Activities created in root scope
  const p1 = fetchData('http://url1.example.com');
  const p2 = fetchData('http://url2.example.com');

  const result = await CancellationScope.cancellable(async () => {
    const first = await Promise.race([p1, p2]);
    // Cancelling this scope does NOT cancel p1/p2 (they belong to root scope)
    CancellationScope.current().cancel();
    return first;
  });

  return result;
}

Cancel an Activity from a Workflow

For an activity to receive a cancellation request, it must:

1. Send heartbeats using Context.current().heartbeat()
2. Have a heartbeat timeout configured in proxyActivities

// In workflow
const { longActivity } = proxyActivities<typeof activities>({
  startToCloseTimeout: '1h',
  heartbeatTimeout: '30s', // REQUIRED for cancellation to work
});

// In activity
import { Context } from '@temporalio/activity';

export async function longActivity(): Promise<void> {
  for (let i = 0; i < 1000; i++) {
    Context.current().heartbeat(i); // send progress
    // If cancelled, heartbeat() will throw CancelledFailure
    await doChunk(i);
  }
}

Exception: Local Activities can be cancelled without heartbeats because they run in the same Worker process.

Reset a Workflow Execution

Use reset when a workflow is stuck due to non-determinism errors or bugs that have been fixed:

temporal workflow reset \
    --workflow-id <workflow-id> \
    --event-id <event-id> \
    --reason "Description of fix applied"

With namespace and TLS:

temporal workflow reset \
    --workflow-id my-workflow \
    --event-id 4 \
    --reason "Fixed non-deterministic code" \
    --namespace my-namespace \
    --tls-cert-path /path/to/cert.pem \
    --tls-key-path /path/to/key.pem

Reset copies the Event History up to the reset point into a new execution and replays from there with current code. Progress after the reset point is discarded.

Common Mistakes

Debugging Tips

• Activity not cancelling: Verify both heartbeat() calls in the activity AND heartbeatTimeout in the proxy config. Without both, cancellation will not propagate.
• CancelledFailure not caught: Check if you are catching the right type. Use isCancellation(err) which handles ActivityFailure and ChildWorkflowFailure wrappers.
• Cleanup not running: Ensure cleanup is inside CancellationScope.nonCancellable(). After the root scope is cancelled, any new operation in a cancellable scope is immediately cancelled.
• Workflow stuck after cancellation: If cleanup hangs, check that the cleanup activity itself completes. Consider adding a timeout around cleanup using withTimeout inside nonCancellable.
• Non-determinism after reset: Reset only works if you have deployed the fixed code. The new execution replays history with current code, so the fix must be in place.
• Scope tree confusion: Remember that an operation is cancelled by the scope it was created in, not the scope it is awaited in. If an activity is created in the root scope, cancelling a child scope will not cancel it.

Further Documentation

If this skill does not answer your question, use Context7 to search /temporalio/sdk-typescript or /temporalio/samples-typescript for more details.

Example queries:

• context7 query /temporalio/sdk-typescript "CancellationScope API and options"
• context7 query /temporalio/samples-typescript "cancellation heartbeating example"
• context7 query /temporalio/sdk-typescript "how to cancel a child workflow"