Two different reasons a task runs twice
A recurring task can overlap its own previous execution, or several servers can start the same scheduled occurrence. These are related but different problems. A nightly report that takes longer than expected needs overlap control; a scheduler running on three web nodes also needs a deliberate runner-selection policy.
Neither mechanism proves exactly-once business completion. A worker may commit a result and then fail before recording completion. The next execution needs a way to recognize the already completed business operation. Design scheduling coordination and result identity as separate boundaries.
Setup: identify the occurrence and its owner
Record the schedule, timezone, task name, expected duration and missed-run policy. Define an occurrence identifier, such as the report type and reporting period. Decide whether a late execution should catch up or be skipped; a framework timer cannot make that business decision for you.
Inventory all hosts invoking the Laravel scheduler and their effective cache configuration. The reviewed Laravel documentation describes cache-backed overlap locks and a shared central cache requirement for single-server scheduling. Check supported stores and method behavior in the installed release. Verify that nodes actually use the same store and namespace rather than assuming matching configuration filenames are sufficient.
Illustrative incident: duplicate financial summaries
An illustrative internal reporting system sends two summaries after another application node is added. Each node's cron entry invokes the scheduler. A separate long-running task also overlaps itself during a slow database period. This constructed example demonstrates why one generic duplicate-job explanation can miss two independent mechanisms.
Capture the occurrence identifier, scheduler host, lock decision, job identifier and durable result. Use synthetic recipients in staging. Do not resolve the incident by rerunning all summaries against real recipient lists while the completion state remains unknown.
Troubleshooting: establish what was duplicated
| Evidence | Investigate | Correction boundary |
|---|---|---|
| Same occurrence starts on different nodes | Shared store and runner-selection policy | Coordinate schedulers across hosts |
| One host starts a task before its prior run ends | Duration and overlap settings | Bound overlap for that task |
| No runner starts after a crash | Lock ownership and expiry evidence | Review stale-lock recovery carefully |
| One job produces the result twice | Durable result identity and retry handling | Add business-level deduplication |
Do not clear every scheduling lock while another worker may still be active. A lock that looks old from one host can still belong to useful work elsewhere. Confirm ownership and process state before a targeted recovery.
Corrective action and safe replay
Give each scheduled task a meaningful unique name, configure the documented coordination methods, and monitor the chosen store. Choose lock expiry according to the execution model and failure recovery needs. If the task dispatches a queued job, make clear whether the scheduler's lock protects dispatch or the entire queued business operation.
Persist a unique occurrence key with the result or operation record so a retry can reconcile instead of repeating an irreversible effect. For email, invoicing or external APIs, distinguish queued, accepted and completed states. A scheduler lock cannot roll back a message already sent to another system.
Verification, SLO and SOP
Run two scheduler hosts against one shared test store. Simulate a slow task, terminate a worker at controlled points, and retry an occurrence whose result already exists. Confirm both normal progress and absence of duplicate business output. Verify that a lock-store outage produces the approved operational behavior rather than silent unlimited execution.
An internal freshness SLO can measure completion of eligible scheduled occurrences by their agreed deadline. A commercial SLA must define missed windows and dependencies separately. The SOP should document occurrence lookup, lock evidence, authorized replay, recipient safeguards and escalation ownership. Retain the failed operation record before changing coordination settings.
See Laravel development and DevOps automation.
Technical reference
Laravel task scheduling, reviewed 19 October 2026. Follow documentation matching the installed product version.