Control Durable Object alarm retry with ctx.abort()’s retryAlarm option

Cloudflare Workers now allow a Durable Object alarm to be stopped permanently by supplying { retryAlarm: false } to ctx.abort(). This gives engineers the ability to prevent an alarm from being re‑triggered after an abort, which is especially useful for one‑off cleanup jobs that would otherwise repeat unintentionally.

What changed in the alarm API

Previously, if an alarm handler called ctx.abort(), the platform would automatically schedule the alarm to run again after the Durable Object instance restarted. The new optional flag retryAlarm defaults to true, preserving the old behavior, but setting it to false tells the runtime to consider the alarm completed and not to retry it.

Why the change matters for engineers

Many Durable Object patterns use alarms for periodic maintenance, such as deleting all stored keys after a retention window. Without the flag, a successful cleanup that ends with ctx.abort() would cause the alarm to fire again, potentially re‑executing expensive logic or re‑instantiating the object’s constructor. By disabling the retry, you avoid duplicate work, reduce unnecessary compute, and keep the object’s lifecycle predictable.

Implementation details and version requirement

The flag is passed as the second argument to ctx.abort(). The change is only effective in local development environments when using Wrangler version 4.126.0 or newer. A minimal example in JavaScript looks like this:

import { DurableObject } from "cloudflare:workers";

export class CleanupTask extends DurableObject {
  async alarm() {
    await this.ctx.storage.deleteAll();
    this.ctx.abort("Cleanup complete", { retryAlarm: false });
  }
}

The same pattern works in TypeScript, with the method returning Promise<void> and the same abort call.

Operational considerations

• Alarms can run at the same time as regular requests to the same Durable Object. If a concurrent request also calls ctx.abort(), its retryAlarm setting controls whether the alarm is retried, so you must apply the flag consistently on every abort path that should stop the alarm.
• The default retry behavior protects against a stray request permanently canceling an alarm. Changing the flag should be a deliberate decision, typically limited to cleanup or one‑off tasks.
• When testing locally, ensure your Wrangler version meets the 4.126.0 minimum; otherwise the flag will be ignored and alarms will continue to retry.

Related CloudNinjas coverage: hands-on guides.

What This Means For Practitioners

• Review any Durable Object alarms that end with ctx.abort() and decide whether automatic retry is desired.
• Update alarm handlers that perform destructive or idempotent operations to include { retryAlarm: false } when the operation should not repeat.
• Audit other request handlers that may abort an in‑progress alarm and apply the same flag if the alarm must be stopped.
• Verify your development toolchain is using Wrangler 4.126.0+ to see the new behavior during local testing.