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.
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:
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1Because 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
| Cause | How to check | Fix |
|---|---|---|
| Cron entry missing | Run crontab -l as the user that should own it. It is often lost after a server rebuild or container redeploy | Add the entry above and keep it in your provisioning or deploy config |
| Wrong user or path | Run 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 binary | Cron has a minimal environment, so php may resolve to another version or nothing | Use the full path, such as /usr/bin/php |
| Time zone | Tasks run at an unexpected hour | The scheduler uses the server's current time. Set the zone with ->timezone(...) or schedule_timezone in config/app.php |
Stuck withoutOverlapping lock | A task never starts, though the scheduler runs | Run php artisan schedule:clear-cache |
onOneServer and cache driver | Tasks run on no server, or on every server | Use the database, memcached, dynamodb or redis cache driver, with all servers on the same central cache |
| Maintenance mode | The app is down with php artisan down | Tasks do not run in maintenance mode. Add evenInMaintenanceMode() if a task must |
| Scheduler paused | Someone ran php artisan schedule:pause, for example during a deploy | Run 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 whyschedule:clear-cacheclears 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:
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:
Schedule::exec('true')
->everyFiveMinutes()
->pingOnSuccess(config('services.heartbeat.scheduler_url'));Set it up in UptimeIO
- Create a monitor and choose the Heartbeat type.
- 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.
- Copy the heartbeat URL into your config and pass it to
pingOnSuccess. - 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
- Cron job monitoring - How UptimeIO heartbeat monitoring works and which plans include it.
- Cron job not running - Causes and fixes for crontab and systemd jobs on your own servers.
- Cron expression generator - Build a schedule and preview its next run times.
- Heartbeat monitoring docs - Settings, ping examples, metadata, and rate limits.