Laravel scheduler not running? Causes, fixes and alerts

Laravel runs every scheduled task from one cron entry, so when that entry is wrong or missing, everything stops at once and nothing reports it. Here is how to find the cause, and how to get an alert the next time it happens.

Updated

Short answer

The scheduler needs one cron entry on the server that runs php artisan schedule:run every minute, as the right user and in the right directory. If that is in place, check the time zone, stuck withoutOverlapping locks, and the cache driver used by onOneServer. Add pingOnSuccess with a heartbeat URL to be alerted when a task stops.

Monitor your Laravel scheduler free

How the scheduler gets triggered

Laravel does not run anything on its own. Your tasks live in routes/console.php, and schedule:run checks which are due at the server's current time. Only a cron entry that calls it every minute makes that happen. The Laravel docs give this entry:

crontabShell
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Because the output goes to /dev/null, a failure here is silent. That is why the scheduler can stop for weeks before anyone notices.

Find the cause

CauseHow to checkFix
Cron entry missingRun crontab -l as the user that should own it. It is often lost after a server rebuild or container redeployAdd the entry above and keep it in your provisioning or deploy config
Wrong user or pathRun the exact command by hand as that user. Look for permission errors or "Could not open input file"Use the real project path and a user that can read the app and write storage/
Wrong php binaryCron has a minimal environment, so php may resolve to another version or nothingUse the full path, such as /usr/bin/php
Time zoneTasks run at an unexpected hourThe scheduler uses the server's current time. Set the zone with ->timezone(...) or schedule_timezone in config/app.php
Stuck withoutOverlapping lockA task never starts, though the scheduler runsRun php artisan schedule:clear-cache
onOneServer and cache driverTasks run on no server, or on every serverUse the database, memcached, dynamodb or redis cache driver, with all servers on the same central cache
Maintenance modeThe app is down with php artisan downTasks do not run in maintenance mode. Add evenInMaintenanceMode() if a task must
Scheduler pausedSomeone ran php artisan schedule:pause, for example during a deployRun php artisan schedule:continue. Mark tasks that must always run with evenWhenPaused()

To confirm Laravel sees your tasks and when they next run, use php artisan schedule:list.

Two details that catch people out

  • `withoutOverlapping` locks last 24 hours by default. If a run is killed by a crash or a deploy, the lock can remain and block the task. Pass a number of minutes, for example withoutOverlapping(10), so a stale lock expires sooner. The lock lives in your cache, which is why schedule:clear-cache clears it.
  • `schedule:work` is for local development. It runs in the foreground and calls the scheduler every minute until you stop it. It is not a replacement for the cron entry on a server.

If you define tasks that run more often than once a minute, schedule:run keeps running until the end of the minute. After a deploy, run php artisan schedule:interrupt so it picks up the new code.

Ping a heartbeat from the schedule

The scheduler has built-in hooks for this. pingOnSuccess sends a request to a URL only if the task succeeds. Laravel counts a task as failed when the Artisan or system command exits with a non-zero code. Add it to any task you care about:

routes/console.phpPHP
use Illuminate\Support\Facades\Schedule;

Schedule::command('reports:generate')
    ->dailyAt('02:00')
    ->withoutOverlapping(30)
    ->pingOnSuccess(config('services.heartbeat.report_url'));

Store the URL in config or an environment variable. It looks like https://heartbeat.uptimeio.com/heartbeat/YOUR_HEARTBEAT_TOKEN and works like a password, so keep it out of the repository.

Laravel also provides pingBefore, thenPing (after the task, success or not), pingOnFailure, and conditional versions such as pingOnSuccessIf($condition, $url). For a heartbeat monitor you want pingOnSuccess: if the task fails, hangs or never starts, no ping arrives and you are alerted.

To know the scheduler itself is alive, add a cheap task that does nothing but ping:

routes/console.phpPHP
Schedule::exec('true')
    ->everyFiveMinutes()
    ->pingOnSuccess(config('services.heartbeat.scheduler_url'));

Set it up in UptimeIO

  1. Create a monitor and choose the Heartbeat type.
  2. Set the interval to match the task, for example 5 minutes for the scheduler check or 24 hours for a daily report, and a grace period longer than the slowest run.
  3. Copy the heartbeat URL into your config and pass it to pingOnSuccess.
  4. Choose where alerts go: email, Slack, Telegram, Pushover or a webhook.

Heartbeat monitors are on every plan, including Free. A few details worth knowing:

  • Intervals: 1 minute to 24 hours, with a grace period of 1 second to 24 hours. The shortest interval is 5 minutes on Free and 1 minute on Pro and Scale.
  • Requests: GET or POST, no authentication.
  • Incidents: an incident opens when a ping is late, and resolves after 3 on-time pings in a row.

Questions

Why is the Laravel scheduler not running?
Most often the cron entry that runs php artisan schedule:run every minute is missing, runs as the wrong user, or points at the wrong path. Run the command by hand as the cron user, check crontab -l, and use full paths.
Why does a scheduled task never start even though the scheduler runs?
A withoutOverlapping lock may be stuck. The lock expires after 24 hours by default. Run php artisan schedule:clear-cache to clear it, and pass a shorter expiry in minutes next time.
Does onOneServer work with any cache driver?
No. Your default cache driver must be database, memcached, dynamodb or redis, and all servers must use the same central cache server.
Should I use schedule:work in production?
The Laravel docs present schedule:work for local development. In production, use the single cron entry that runs schedule:run every minute.
How do I get an alert when a Laravel scheduled task fails?
Add pingOnSuccess with a heartbeat URL to the task. The ping is sent only when the command exits successfully, so the heartbeat monitor alerts you when it fails, hangs or never starts.

Related

Start monitoring in a few minutes

Start monitoring free

Free plan · 50 monitors · No credit card required