Aglet

How to diagnose job retries by attempt and side effect

A retry can recover a transient failure or repeat a side effect that already happened. This triage guide follows one logical job through enqueue, attempts, errors, retry scheduling, and final state, then compares it with a job that completed on its first attempt.

Establish what is happening

  1. Capture one logical job identity

    Record the public job identifier, enqueue time, attempt starts and ends, failure class, retry decision, backoff interval, worker context, input shape, and final state. Link side effects by stable identifiers and redact payload values. Distinguish one job with attempts from multiple jobs with similar inputs.

  2. Compare first-attempt and retry paths

    Align a retrying job with a successful first-attempt job of the same type and input structure. Compare validation, external calls, transactions, locks, acknowledgments, and output records. Mark whether the failure happened before or after a side effect and preserve evidence for each attempt.

  3. Check exhaustion and recovery behavior

    Inspect what happens when retries succeed, fail again, or reach their configured limit. Record final status, alert or review path, partial records, and whether a manual replay is possible without duplication. Treat a stuck or repeatedly failing job as a separate operational outcome.

What to carry forward

Return a scope statement naming job type, attempt boundary, failure class, side-effect status, retry outcome, and uncertainty. Route the next work to idempotency, failure classification, scheduling, or observability. Stop when one logical job and one matched completion provide a bounded investigation.

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