Replay Missed Laravel Tasks With Schedule Catchup | Mohamed Said       [Skip to content](#main)  [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://msaied.com) - [Home](https://msaied.com)
- [Projects](https://msaied.com/projects)
- [Articles](https://msaied.com/articles)
- [Certificates](https://msaied.com/certificates)
- [About](https://msaied.com#about)

           [  Contact](https://msaied.com#contact) Menu 

Menu
----

Close 

 - [HomeStart here](https://msaied.com)
- [ProjectsCase studies](https://msaied.com/projects)
- [ArticlesEngineering notes](https://msaied.com/articles)
- [CertificatesCredentials](https://msaied.com/certificates)
- [AboutHow I work](https://msaied.com#about)
- [ContactGet in touch](https://msaied.com#contact)

  [Start a conversation](https://msaied.com#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 

 1. [Home](https://msaied.com)
2. /
3. [Articles](https://msaied.com/articles)
4. /
5. [Laravel](https://msaied.com/articles?category=laravel)
6. /
7. Replay Missed Laravel Scheduled Tasks With Schedule Catchup

   [Laravel](https://msaied.com/articles?category=laravel) [Composer Pacakge](https://msaied.com/articles?category=composer-pacakge) 

 Replay Missed Laravel Scheduled Tasks With Schedule Catchup
============================================================

 Schedule Catchup is a Laravel package that records scheduler activity in the database and automatically replays tasks missed during server downtime, so critical jobs like daily reports are never silently skipped.

 ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://msaied.com#person) Published 9 Nov 2026 · Updated 14 Nov 2026 · 4 min read

ShareCopy linkCopied

 ![Replay Missed Laravel Scheduled Tasks With Schedule Catchup](https://cdn.msaied.com/823/3443348a15b03db8960a1180670529ff.png) 

  On this page +1. [The Problem: Laravel Silently Skips Missed Scheduled Tasks](#the-problem-laravel-silently-skips-missed-scheduled-tasks)
2. [Installation](#installation)
3. [Marking Tasks for Replay](#marking-tasks-for-replay)
4. [Using the Correct Date During Replay](#using-the-correct-date-during-replay)
5. [Inspecting and Controlling Recovery](#inspecting-and-controlling-recovery)
6. [Replay Safety Considerations](#replay-safety-considerations)
7. [Key Takeaways](#key-takeaways)

 The Problem: Laravel Silently Skips Missed Scheduled Tasks
----------------------------------------------------------

When your server goes offline at midnight, Laravel's scheduler does not backfill the tasks it missed. A daily report command that was supposed to run at `00:00` simply never executes, and there is no built-in mechanism to recover it once the server comes back online.

[Schedule Catchup](https://github.com/cyberwizard-dev/schedule-catchup), a package by Arowosaye Remilekun, solves this by recording scheduler activity in the database and checking for missed runs every time the scheduler resumes.

Installation
------------

The package requires PHP 8.2 or newer and supports Laravel 11, 12, and 13.

```bash
composer require cyberwizard/schedule-catchup
php artisan migrate

```

The auto-discovered service provider schedules catch-up and heartbeat commands every five minutes, plus daily pruning of settled history with a default 90-day retention period.

Marking Tasks for Replay
------------------------

Not every scheduled command should be replayed. Add `replayOnCatchup()` to the events you want to recover:

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command('reports:daily')
    ->dailyAt('00:00')
    ->withoutOverlapping()
    ->onOneServer()
    ->replayOnCatchup();

```

Only events tagged this way qualify for recovery. A daily report that must exist for each calendar day is a good candidate. A poller that already checks for outstanding work every five minutes is not — replaying its missed invocations adds little value.

On its very first run, with no previous checkpoint, the package records a baseline rather than attempting to recover an unknown history.

Using the Correct Date During Replay
------------------------------------

Replaying an old command naively can produce wrong results if the command calculates its reporting period from `now()`. A daily report replayed on Saturday should use Friday's data, not today's.

The `ResolvesScheduledTime` trait provides a `scheduledFor()` helper. During replay it returns the missed occurrence's original timestamp; during a normal run it returns the current time.

```php
namespace App\Console\Commands;

use Cyberwizard\ScheduleCatchup\Traits\ResolvesScheduledTime;
use Illuminate\Console\Command;

class DailyReport extends Command
{
    use ResolvesScheduledTime;

    protected $signature = 'reports:daily';

    public function handle(): int
    {
        $reportDate = $this->scheduledFor()->subDay()->toDateString();

        $this->info("Reporting date: {$reportDate}");

        // Generate or update the report for $reportDate here.

        return self::SUCCESS;
    }
}

```

The trait also exposes `isCatchupReplay()` for commands that need different behaviour during recovery versus a normal invocation.

Inspecting and Controlling Recovery
-----------------------------------

Before executing a replay, you can inspect what would run:

```bash
php artisan schedule-catchup:run --dry-run --only=reports:daily

```

The `--only` flag matches a substring of the event summary. Remove `--dry-run` to execute. Note that a filtered run does not advance the global checkpoint.

The default occurrence cap is 50 per cron walk. Version 1.1.0 stores a cursor when that cap is reached, so the remaining backlog continues on later passes. Failed occurrences are retried up to `max_attempts` times (default: 3). Overlapping runs are deferred rather than marked as failures.

The package dispatches `ScheduleCatchupCompleted` after successful replays and `ScheduleCatchupFailed` for new failures or exhausted attempts, giving you hooks for notifications.

Replay Safety Considerations
----------------------------

Idempotency is your responsibility. If a command sends an email and then crashes before the package records success, a retry will send the email again. Design commands to check whether work was already completed before a previous failure — for example, by upserting a record keyed by reporting date.

For multi-server setups, configure shared cache storage for scheduler mutexes and package locks.

Key Takeaways
-------------

- Add `replayOnCatchup()` only to tasks where replaying missed runs is meaningful.
- Use the `ResolvesScheduledTime` trait to ensure replayed commands operate on the correct historical date.
- Use `--dry-run` with `--only` to inspect pending replays before committing.
- Commands must be idempotent — the package can retry, but it cannot prevent duplicate side effects.
- Keep existing scheduler monitoring in place; recovery only works once the scheduler is running again.

---

Source: [Replay Missed Laravel Scheduled Tasks With Schedule Catchup — Laravel News](https://laravel-news.com/schedule-catchup)

- [Laravel](https://msaied.com/articles?search=Laravel)
- [Scheduler](https://msaied.com/articles?search=Scheduler)
- [Package](https://msaied.com/articles?search=Package)
- [Cron](https://msaied.com/articles?search=Cron)
- [Task Recovery](https://msaied.com/articles?search=Task%20Recovery)

 Frequently asked questions 
---------------------------

  Does Schedule Catchup replay all scheduled tasks automatically after downtime?No. Only tasks explicitly tagged with `replayOnCatchup()` in your schedule definition are eligible for recovery. All other tasks are ignored by the package.

   How do I make sure a replayed command uses the original scheduled date instead of the current time?Add the `ResolvesScheduledTime` trait to your command and replace `now()` calls with `$this-&gt;scheduledFor()`. During a replay this returns the missed occurrence's original timestamp; during a normal run it returns the current time.

   What happens if a replayed command fails partway through and causes a duplicate side effect on retry?The package retries failed occurrences up to `max\_attempts` times (default 3), but it cannot prevent duplicate side effects. You must write idempotent commands — for example, upserting a record keyed by reporting date — to avoid issues like duplicate emails.

   ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author
----------------

[Mohamed Said](https://msaied.com#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow.

[About](https://msaied.com#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)  

   [Previous articleInsert Middleware Before or After Existing Laravel Middleware (Laravel 13.40)](https://msaied.com/articles/insert-middleware-before-or-after-existing-laravel-middleware-laravel-1340) [Next articleLaravel Read Replicas: Check if a Replica Has Caught Up with Commit IDs](https://msaied.com/articles/laravel-read-replicas-check-if-a-replica-has-caught-up-with-commit-ids)  

   On this page
-------------

1. [The Problem: Laravel Silently Skips Missed Scheduled Tasks](#the-problem-laravel-silently-skips-missed-scheduled-tasks)
2. [Installation](#installation)
3. [Marking Tasks for Replay](#marking-tasks-for-replay)
4. [Using the Correct Date During Replay](#using-the-correct-date-during-replay)
5. [Inspecting and Controlling Recovery](#inspecting-and-controlling-recovery)
6. [Replay Safety Considerations](#replay-safety-considerations)
7. [Key Takeaways](#key-takeaways)

 ###  Have a technical challenge?

 Tell me what you’re building. I reply within two working days.

[Start a conversation](https://msaied.com#contact) 

   Related articles
-----------------

 [ ![](https://cdn.msaied.com/824/9cedece04b58444cb565a8bec2be1737.png) Laravel · 4 min read### Laravel AI SDK 1.4: Agents Now Recover From Tool Failures

12 Nov 2026 ](https://msaied.com/articles/laravel-ai-sdk-14-agents-now-recover-from-tool-failures) [ ![](https://cdn.msaied.com/822/5e40cb946aeac937ab3dc0017777ec8b.png) Laravel · 4 min read### Laravel Read Replicas: Check if a Replica Has Caught Up with Commit IDs

11 Nov 2026 ](https://msaied.com/articles/laravel-read-replicas-check-if-a-replica-has-caught-up-with-commit-ids) [ ![](https://cdn.msaied.com/821/88459f9998da0239229cdbcb6f7daa6c.png) Laravel · 3 min read### Insert Middleware Before or After Existing Laravel Middleware (Laravel 13.40)

6 Nov 2026 ](https://msaied.com/articles/insert-middleware-before-or-after-existing-laravel-middleware-laravel-1340) 

  Have a technical challenge?
----------------------------

Tell me what you’re building. I reply within two working days.

 [Discuss your project ↗](https://msaied.com#contact) 

  © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow.

 - [Home](https://msaied.com)
- [Articles](https://msaied.com/articles)
- [Certificates](https://msaied.com/certificates)
- [GitHub](https://github.com/EG-Mohamed)
- [LinkedIn](https://www.linkedin.com/in/msaiedm/)
- [WhatsApp](https://wa.me/201094619204)
- [Email Address](mailto:hello@msaied.com)
- [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)
- [Sitemap](https://msaied.com/sitemap.xml)
