Aglet

How to diagnose failing scheduled work by run boundary

Scheduled work can fail before it is enqueued, while waiting for a worker, during execution, or after a partial result. This triage guide follows one expected run from due time to final state, compares a nearby successful run, and checks overlap, retry, and missed-window behavior.

Establish what is happening

  1. Define the expected scheduled run

    Record schedule identity, intended due time, timezone or calendar context, input shape, target account or dataset class, run identifier, enqueue and claim times, worker attempt, dependency state, and final outcome. Include whether another run overlapped and redact sensitive payload values.

  2. Check every run boundary

    Look for schedule calculation, due selection, enqueue, queue acceptance, claim, handler start, lock, dependency calls, commit, retry, and visible completion. Mark the first absent or late boundary. Distinguish a missed run from a run that executed but failed to publish its outcome.

  3. Compare an adjacent successful run

    Choose the same schedule with a nearby successful occurrence and compare calendar calculation, input, worker availability, duration, dependency response, overlap, retry, and final state. Note changes in release, data size, timezone, or clock context rather than averaging different schedule cases.

What to carry forward

Return a scope statement naming schedule, expected and actual run times, first failing boundary, adjacent success, final state, overlap, and uncertainty. Route next work to scheduling, enqueue, workers, dependencies, retries, or visibility. Stop when one due run can be traced end to end.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow