Skip to content

jackson2w/claude-code-skills / cloudflare-workers-cron-email

cloudflare-workers-cron-email

Verified

This skill should be used when the user asks to debug a Cloudflare Workers Cron Trigger that "isn't firing" or "not running" (or fires on the wrong day), set up or troubleshoot the send_email binding or Email Routing destination addresses for Workers, size a Worker against Cloudflare's per-invocation subrequest limits, test a scheduled() handler locally against real R2/KV/email bindings, verify an R2 delete/rename actually took effect, or rename/reorganize keys in an R2 bucket. Trigger phrases include "cron trigger not firing", "scheduled worker not running", "cron ran on the wrong day", "wrangler cron", "cron trigger debug", "send_email binding", "Workers email binding", "Email Routing destination address", "workers subrequest limit", "test-scheduled --remote", "r2 object rename", "r2 delete not working", "r2 move objects".

Cloudflare Workers: Cron Triggers + Email Bindings

Diagnose scheduled Cloudflare Workers that silently fail to run, size a Worker's R2/KV workload against subrequest limits before it's built, and wire up the send_email binding correctly the first time. This knowledge comes from a real debugging session where a correctly-configured cron trigger and a correctly-coded Worker both looked broken for reasons that took real investigation to isolate.

Core principle: distrust wrangler tail for "did it run?"

wrangler tail can attach to a stale or reused session and replay old log lines instead of showing genuinely new activity — it produced byte-identical output (down to the same historical timestamp) across two separate invocations during testing, several minutes apart, while a cron trigger was firing on a 2-minute schedule. Treat wrangler tail as useful for watching a Worker interactively, never as the ground truth for "has this invocation happened."

For ground truth, use two Cloudflare APIs instead:

  1. Is the schedule registered? GET /accounts/{account_id}/workers/scripts/{script_name}/schedules Returns the cron pattern and created_on/modified_on timestamps. See scripts/check-schedule-registered.sh.

  2. Has it actually invoked? The GraphQL Analytics API's workersInvocationsAdaptive dataset, filtered by scriptName and a datetime range, returns real invocation counts (sum.requests, sum.errors) per time bucket — independent of tail, independent of the dashboard's "Requests" tile (which does reflect cron invocations, but only after they've happened). See scripts/check-cron-invocations.sh. Full query template in references/diagnosing-cron.md.

GraphQL Analytics has real ingestion lag — do not conclude "broken" too early

Live-polling workersInvocationsAdaptive every 30s for 10+ minutes showed a flat, unchanging invocation count while a 2-minute cron was, in fact, firing correctly the entire time — confirmed after the fact by both a later query against the same time window (which then showed every 2-minute tick present) and by finding real copied output in the target R2 bucket from those runs. The analytics pipeline had not finished ingesting recent minutes yet, and a flat "stuck" count during live polling looks identical to a genuinely broken dispatcher. Do not conclude the cron dispatcher is broken from a live polling session alone, no matter how long you wait (10-15+ minutes of flat zero is not conclusive) — instead, check for a real side effect of the job (a new/changed object in the target bucket, a row in a database, etc.), or re-run the same GraphQL query later, after stepping away, to let ingestion catch up.

Separately, multiple Cloudflare Community threads do document real cases where Cron Triggers register (visible via /schedules) but genuinely never invoke scheduled() at all, with no error anywhere and no fix from redeploying. That failure mode exists — but distinguish it from analytics lag by checking for real side effects before concluding the dispatcher itself is broken, not just by an unchanging analytics count. This section is time-bound either way — re-verify before treating either claim as current fact.

Testing scheduled() directly, bypassing the cron dispatcher entirely

wrangler dev --test-scheduled --remote exposes a local /__scheduled route that invokes the Worker's scheduled() handler directly against its real bound resources (R2, KV, email, etc.), without going through Cloudflare's cron dispatcher at all. This is the fastest way to prove the code is correct, independent of whether the dispatcher is currently reliable.

npx wrangler dev --test-scheduled --remote --port 8787 &
curl "http://localhost:8787/__scheduled?cron=0+9+*+*+1"

Ceiling: this tunnel has an effective ~90-120 second limit before it fails with a 502/504, even though a real deployed cron invocation gets up to 15 minutes wall-clock. A job that legitimately needs longer than that (e.g., a full-corpus R2 sync over many hundreds of objects) will fail here every time, for reasons unrelated to correctness — do not keep retrying the same full-scope test expecting a different result.

Workaround: temporarily scope the operation down so the test completes in seconds — e.g., add a prefix filter to an R2 list() call, or limit to one small subset of the real workload — to get a fast, decisive pass/fail signal against real bindings. Mark the temporary change clearly in the code (e.g. a // TEMP test scope — revert before final deploy comment) and track it explicitly; it is easy to leave a test-only schedule or scope change live through several redeploy cycles. Do a final review of the diff before the production deploy to confirm every temporary knob was reverted.

Cron Trigger day-of-week is 1=Sunday..7=Saturday, not the Unix convention

Cloudflare's cron day-of-week field runs 1=Sunday through 7=Saturday — different from standard Unix cron (where 0 or 7 = Sunday, 1 = Monday). A schedule written as 0 9 * * 1 intending "Monday 9am" is actually "Sunday 9am" on Cloudflare, and will fire a day early with no error anywhere — it's a silent semantic mismatch, not a bug in the dispatcher. Confirmed via a real case: a backup Worker's wrangler.toml had crons = ["0 9 * * 1"] commented "Weekly, Monday 09:00 UTC", and R2 snapshot object dates it wrote each run proved it was actually firing every Sunday.

Use the three-letter form (MON, TUE, SUN, ...) instead of a numeric day-of-week — Cloudflare's own docs recommend this specifically to avoid the ambiguity. Verify the fix took effect with scripts/check-schedule-registered.sh (or the dashboard's Triggers → Settings tab, which shows a human-readable "Schedule: ... Next: ..." line — note there's no manual "run now" button there, only edit/delete; see the "Testing scheduled() directly" section above for how to actually fire it on demand).

R2 deletes/renames: HEAD/GET can lag, but the objects-list endpoint doesn't

Renaming or reorganizing keys in an R2 bucket means copy-then-delete for every object — R2 has no move/rename command, only wrangler r2 object get/put/delete (or the equivalent API calls) per key.

After deleting an object, a direct HEAD/GET on that same key (via wrangler r2 object get or the REST API) can keep returning 200 + the old body for 15+ seconds after both the CLI and a direct API DELETE report success — this looks exactly like the delete silently failing. It isn't: the bucket's objects-list endpoint (GET /accounts/{account_id}/r2/buckets/{bucket}/objects?prefix=...) reflects the true state immediately and consistently on repeat queries, even while HEAD/GET is still lagging. When verifying a bulk delete or rename, check with a prefix list, not a single HEAD/GET — the same "don't trust one check, verify with a real side effect" principle as the cron-invocation guidance above, just for R2 instead of cron.

Sizing a Worker against subrequest limits (do this before writing the loop)

Any Worker that loops over R2/KV objects (list, then get/head/put per object) burns subrequests fast. Check the budget before designing the operation, not after it fails in production:

PlanSubrequests / invocationCron CPU timeWall-clock (scheduled)
Free5010ms15 min (shared cap)
Paid ($5/mo base)10,00030s (<1hr interval) / 15min (≥1hr interval)15 min

Estimate: object_count × ops_per_object (a get+put pair is 2; add a head for change-detection and it's 3). A few hundred objects at 3 ops each already exceeds the free tier's 50-subrequest cap. If the estimate exceeds 50, Workers Paid is required — this is a real, non-optional cost tradeoff to surface to the user before building, not after deploying and hitting a wall.

send_email binding facts (get these right the first time)

Full wrangler config syntax and API shape in references/email-binding.md. The two facts that are easy to get backwards:

  • from address: must be on a domain (zone) that has Cloudflare Email Routing enabled — Cloudflare needs that zone's SPF/DKIM records to authenticate outgoing mail. This is the only place DNS/MX matters.
  • Destination address (the to): verification is account-level and fully independent of that address's own domain DNS. Add it under Email Routing → Destination Addresses; Cloudflare emails a confirmation link; clicking it verifies the address. No MX/Email Routing changes are needed on the destination domain at all — it can be a Gmail address, a personal domain with unrelated email hosting, anything.

Because enabling Email Routing on a zone rewrites its MX/SPF/DKIM records, do not enable it on a domain that already has live email service without explicit confirmation — prefer a spare/unused domain dedicated to outbound Worker sending, and point the destination address at wherever the human actually reads mail (their real personal address), using the account-level verification above. Sending to a verified destination address is free on every plan and does not count toward quota.

Quick diagnostic checklist

When "the scheduled job isn't producing its expected output" (email, sync, etc.), work through in this order:

  1. Confirm the schedule is registered (scripts/check-schedule-registered.sh).
  2. Look for a real side effect of the job (a new/changed object in the target bucket, etc.) — this is more conclusive than any analytics query, since analytics can lag by many minutes.
  3. If no side effect and scripts/check-cron-invocations.sh shows zero, wait longer and re-query rather than trusting a single live-polling session — ingestion lag alone can produce a flat "stuck" reading that looks identical to a genuinely broken dispatcher. Do not stop at wrangler tail silence either; it can replay a stale session instead of showing nothing.
  4. Only after a real side-effect check plus a delayed re-query both come back empty, suspect the platform-level dispatcher issue described above.
  5. Independently verify the code path directly via --test-scheduled --remote with a scoped-down operation size — this bypasses the dispatcher and analytics lag entirely, and is the fastest way to isolate "is it the code or the platform."
  6. If that also fails, check the subrequest budget against the plan tier.
  7. If email specifically fails with "destination address is not a verified address", that's the account-level verification step, not a DNS/config bug — and don't assume a prior "yes it's verified" from a human is necessarily accurate; the error message is ground truth.

Additional resources

  • references/diagnosing-cron.md — full GraphQL Analytics query template, /schedules API details, and how to read the results.
  • references/email-binding.md — wrangler.toml/jsonc send_email syntax variants (destination_address, allowed_destination_addresses, allowed_sender_addresses), the structured env.EMAIL.send() API shape, and the EmailAddress object form for a display name.
  • scripts/check-schedule-registered.sh — curl wrapper for the /schedules endpoint.
  • scripts/check-cron-invocations.sh — curl+GraphQL wrapper that prints total invocation count for a script over a given time range.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall