If your Laravel Scheduler tasks are not running, the cause is almost always in one of three layers: the cron daemon itself (not installed, stopped, or no crontab entry), a wrong PHP or artisan path in crontab, or tasks being silently skipped because of the withoutOverlapping() mutex or a mismatched timezone. Before changing anything, run three quick checks: php artisan schedule:list (are the tasks registered?), crontab -l (do you even have a cron entry?), and php artisan schedule:run (does artisan respond when run manually?). The detail that trips most developers up is that Laravel logs nothing when it skips a task; there was even a confirmed bug in Laravel 12.0 that ran sub-minute tasks only every other minute (issue #57070). The rest of this article shows exactly which layer is broken, which log to read, and when the problem is Laravel itself rather than your config.
Why Do You Never See a Scheduler Error?
Unlike many frameworks, the Laravel Scheduler is not a daemon itself. The official documentation tells you to set up a single cron entry that runs php artisan schedule:run every minute, and Laravel handles the rest (Task Scheduling docs). That means three independent layers must all work at the same time:
- The operating system: is the cron daemon active and is the entry actually running every minute?
- The PHP binary: is the PHP path correct? Are extensions loaded?
- Laravel: do the tasks show up in
schedule:list? Is a mutex or timezone blocking them?
If any layer breaks, the Scheduler stops working but the OS and PHP raise no errors. That is what makes debugging hard. The table below collects the most common scenarios and their symptoms:
| Scenario | Symptom |
|---|---|
| crontab not installed or not active | No scheduler output in cron.log at all |
| PHP or artisan path is wrong | No such file or directory in the log |
| Tasks are in maintenance mode | schedule:list shows them but they do not run |
The withoutOverlapping mutex has not expired |
Task runs once, then gets skipped |
Mismatched timezone (server vs schedule_timezone) |
Task runs at the wrong time or not at all |
A Laravel bug (e.g. everyTenSeconds in Laravel 12.0) |
An entire minute gets skipped |
| env-var from Docker not reaching the scheduler | Config is not loaded correctly |
Prerequisites
This guide assumes you work with Laravel 10/11/12, know your way around routes/console.php or app/Console/Kernel.php, and have defined at least one task with Schedule::command(...) or $schedule->command(...). If you are new to cron, start with crontab.guru or man crontab.
Environment Matrix: VPS, cPanel, Docker
First identify your platform, because the fix differs:
| Platform | Cron daemon | Typical PHP path | Cron user | Where to log |
|---|---|---|---|---|
| VPS Ubuntu | systemd via crontab -e or /etc/cron.d/ |
/usr/bin/php or a versioned path like /usr/bin/php8.3 |
root or www-data |
storage/logs/cron.log (recommended) |
| cPanel / DirectAdmin | The panel's own daemon | /usr/bin/php or /usr/local/bin/php |
cPanel user | Panel's internal log or ~/logs/ |
| Docker (separate container) | supercronic or cron inside the container | /usr/local/bin/php (official php image) |
root (default) | storage/logs/cron.log |
| Laravel Forge / Ploi | The platform's daemon | /usr/bin/php8.X |
platform user | The platform's log |
Key point: the PHP path in the cron entry must be absolute. If which php works in your shell but not in cron, the PATH differs in the cron environment. Always write the full path.
Step 1: Diagnose With Four Commands
Before changing anything, run these four commands in sequence. Each checks a different layer:
# 1. Are the tasks registered in Laravel?
php artisan schedule:list
# 2. Do you have a crontab entry?
crontab -l
# 3. Does artisan work when run manually?
php artisan schedule:run
# 4. Is the cron daemon itself active?
systemctl status cron --no-pager
Separate the three main outcomes. If schedule:list is empty, the problem is in routes/console.php or app/Console/Kernel.php and no task is registered at all. If the list is populated but a manual schedule:run produces no useful output, the problem is in artisan or the execution environment. If a manual schedule:run works but you have no crontab entry, or your log stays empty, the problem is the cron daemon layer.
Why Are Skips Silent?
From the official Laravel 12.x source (vendor/laravel/framework/src/Illuminate/Console/Scheduling/ScheduleRunCommand.php):
protected $signature = 'schedule:run {--whisper : Do not output message indicating that no jobs were ready to run}';
And from Event.php (line 146):
public function shouldSkipDueToOverlapping()
{
return $this->withoutOverlapping && ! $this->mutex->create($this);
}
In other words, when a task is skipped due to overlap, Laravel does not throw an explicit exception; it skips silently and writes nothing to the log. That is exactly why "everything looks correct but the task does not run" happens so often.
Step 2: The Quick Fix
2.1 VPS Ubuntu
This is the shape the official documentation recommends (Running the Scheduler); make the PHP path absolute:
crontab -e -u www-data
* * * * * cd /var/www/your-project && /usr/bin/php8.3 artisan schedule:run >> /dev/null 2>&1
Four critical notes:
cdbefore artisan: Laravel needs the working directory to find.envandvendor/.- Absolute PHP path:
which phpin your shell may output a different path than the cron environment sees. >> /dev/null 2>&1: silences the output of every run; point it at a log file instead if you want one.- The right user:
-u www-dataapplies when PHP-FPM runs aswww-data; adjust if you deploy as another user.
After saving, confirm registration and that cron is active:
crontab -l -u www-data
systemctl status cron
2.2 cPanel (Without Root Access)
cPanel > Cron Jobs
Command: cd /home/username/public_html && /usr/bin/php artisan schedule:run >> /dev/null 2>&1
Schedule: Once per minute (* * * * *)
Find the PHP path in the panel's MultiPHP Manager; it is usually /usr/bin/php or /usr/local/bin/php. If you get the path wrong, the error typically arrives in the email the panel sends you, not in the site's log.
2.3 Docker (Separate Scheduler Container)
For containers, supercronic is a lightweight cron daemon that fits well:
FROM alpine:3.19
RUN apk add --no-cache supercronic
COPY crontab /etc/crontab
CMD ["supercronic", "/etc/crontab"]
* * * * * cd /var/www && /usr/local/bin/php artisan schedule:run >> /var/www/storage/logs/cron.log 2>&1
Important Docker note: the scheduler container must use the same image as the app and mount the same volume, otherwise it cannot see the artisan and .env files. If env-vars do not reach the scheduler, issue #46956 reports exactly this scenario, and the usual cause is that the env-var is defined only in docker-compose; write the value in Laravel's own .env too. If you use config:cache in production, our article on why .env changes are not applied covers that behavior in full.
Step 3: The Root-Cause Fix
3.1 Timezone: Three Layers Must Agree
Check the three timezone layers one by one (outputs are examples):
# 1. Server timezone
date
# Example output: Tue Aug 18 02:30:00 +0330 2026
# 2. PHP timezone
php -r 'echo date_default_timezone_get()."\n";'
# Example output: Asia/Tehran
# 3. Laravel timezone
php artisan tinker --execute="echo config('app.timezone').PHP_EOL;"
# Example output: Asia/Tehran
Set it in .env:
APP_TIMEZONE=Asia/Tehran
And in config/app.php. According to the official docs, you can define a schedule_timezone option next to timezone so all scheduled tasks are evaluated in one timezone (Timezones):
'timezone' => 'UTC',
'schedule_timezone' => 'Asia/Tehran',
Or use the timezone() method for a single task:
Schedule::command('report:generate')
->timezone('Asia/Tehran')
->dailyAt('2:00');
Two notes from the official docs and source:
- DST: some timezones use daylight saving time, and around the clock change your task may run twice or not at all. Laravel's docs recommend avoiding separate timezone scheduling when possible.
- Restart cron: after changing the server timezone, services including cron usually need a restart. Laravel maintainer jbrooksuk said exactly this in issue #49211: "Changing a server's timezone often requires restarting various services,
cronbeing one of them."
sudo systemctl restart cron
3.2 withoutOverlapping and the Mutex
When you call withoutOverlapping(), Laravel creates an atomic lock using your cache. From the 12.x source (ManagesAttributes.php):
public function withoutOverlapping($expiresAt = 1440)
{
$this->withoutOverlapping = true;
$this->expiresAt = $expiresAt;
return $this->skip(function () {
return $this->mutex->exists($this);
});
}
The default expiresAt is 24 hours, according to the official docs (Preventing Task Overlaps). So if a task crashes without clearing its lock, the next run can be skipped for up to 24 hours. To clear these cache locks there is php artisan schedule:clear-cache.
A timing example (hypothetical): a task that should run every 10 minutes but takes 15:
Schedule::command('slow:task')
->everyTenMinutes()
->withoutOverlapping(5); // the lock expires after 5 minutes
00:00 task starts
00:10 cron runs schedule:run => mutex active => skip
00:15 first task finishes
00:20 cron runs schedule:run => mutex still active => skip
00:25 lock expired => new task starts
Common mistake: setting expiresAt too short. If a task normally takes 20 minutes and you call withoutOverlapping(10), the lock expires before the task finishes and parallel runs start.
Rule of thumb: set expiresAt to roughly twice the task's maximum duration. For a 5-minute task, use withoutOverlapping(10).
3.3 Sub-Minute Tasks and the Laravel 12.0 Bug
According to the docs, when you define sub-minute tasks (like everyTenSeconds()), the schedule:run command keeps running until the end of the current minute instead of exiting immediately, so the sub-minute tasks get invoked throughout the minute (Sub-Minute Scheduled Tasks). The docs recommend that sub-minute tasks either dispatch queued jobs or run with runInBackground(), because a slow sub-minute task delays the later ones. On deploys, php artisan schedule:interrupt cuts off an in-progress schedule:run so the old process does not keep serving old code.
On top of this behavior, a bug was confirmed: in issue #57070 on Laravel 12.0, sub-minute tasks ran every other minute, with the middle minute skipped entirely. The fix was developed in PR #59331, which was merged into Laravel's 13.x branch in March 2026; check the changelog of the release you upgrade to so you know the fix is included. Until then, if you are on Laravel 12.0, prefer minute-level frequencies or keep the task short and run it with runInBackground().
3.4 schedule:work for Development
If you do not want to wait for every minute on your local machine, use schedule:work:
php artisan schedule:work
# or with output to a file:
php artisan schedule:work --run-output-file=/tmp/schedule.log
From the official source (ScheduleWorkCommand.php):
protected $signature = 'schedule:work
{--run-output-file= : The file to direct <info>schedule:run</info> output to}
{--whisper : Do not output message indicating that no jobs were ready to run}';
This daemon checks every second and is meant for local development only; the docs are explicit that on production servers you use the cron entry instead.
Quick Reference: One Symptom, One Cause
| Symptom | First check | Likely cause |
|---|---|---|
schedule:list is empty |
Open routes/console.php |
No schedule defined |
schedule:run returns Command not found |
Run artisan with an absolute path | artisan is not in the cron PATH |
| crontab entry exists but the log stays empty | systemctl status cron |
The cron daemon is stopped |
| Task runs once, then gets skipped | Check the cache locks | withoutOverlapping without enough expiresAt |
| Task runs at the wrong time | date and config('app.timezone') |
Timezones out of sync |
| env-var does not reach the scheduler in Docker | Set the env-var in the scheduler container too | issue #46956 |
| Error arrives by email from cPanel | Look at "MultiPHP Manager" | Wrong PHP path |
Common Errors and Fixes
Error 1: No scheduled commands are ready to run.
This is not an error; it means the tasks are registered but none are due right now. For an instant test, add a temporary every-minute task:
Schedule::command('inspire')->everyMinute();
php artisan schedule:run
If it prints the Inspiring quote, Laravel itself is fine and the problem is in the cron layer.
Error 2: Class "X" not found in schedule:run
Usually caused by composer install --no-dev in production removing dev packages, or a broken autoload cache:
composer dump-autoload --optimize
php artisan config:clear
Error 3: Tasks Do Not Run in Maintenance Mode
Per the docs, scheduled tasks do not run while the application is in maintenance mode with php artisan down, so they do not interfere with ongoing maintenance. If a critical task must run even then:
Schedule::command('critical:task')
->hourly()
->evenInMaintenanceMode();
Error 4: Docker env-vars Do Not Reach the Scheduler
Issue #46956, confirmed: when an env-var is set only in docker-compose, the scheduler process may not have access to it. Write the value in Laravel's own .env as well, and mind config:cache after making changes.
Our Tool: Debug Faster With Nyx
Collecting logs, crontab and command output during debugging is a lot of manual work. Nyx, Captain Code's AI assistant, can take those artifacts and review the log with you, suggesting the next debugging step. Our article on automated testing and deployment with GitHub Actions also shows how to run schedule:run as a CI smoke test so problems surface before they reach the server. If your project uses queues, our guide to queue workers and Supervisor is the natural companion to this one.
Frequently Asked Questions
1. Why are my tasks in schedule:list but not running?
Usually one of three: you have no crontab entry, the cron daemon is stopped, or the withoutOverlapping mutex is still active. Work through the Step 1 checklist, and if you suspect the mutex run php artisan schedule:clear-cache.
2. What is the difference between schedule:run and schedule:work?
schedule:run executes once; it is exactly what cron does every minute. schedule:work is a daemon that checks every second and is for local development only, not production.
3. How can I test without waiting?
php artisan schedule:run
It does what cron does every minute. If it produces correct output but cron does not run it, you are missing the crontab entry or the daemon is stopped.
4. How do I know cron is actually running?
Create a test task that appends to a log file every minute:
Schedule::call(function () {
file_put_contents(storage_path('logs/cron-heartbeat.log'),
now().' scheduler is alive'.PHP_EOL, FILE_APPEND);
})->everyMinute();
Then tail -f storage/logs/cron-heartbeat.log; if a new line appears every minute, cron is alive.
5. How do I troubleshoot in cPanel without SSH?
In "Cron Jobs", use the Run Command button; the output appears on the same page. If you see an error, check the PHP path in "MultiPHP Manager".
6. Is the Scheduler in Laravel 11/12 different from Laravel 10?
There are structural changes: from Laravel 11 on, tasks are defined with the Schedule facade in routes/console.php instead of app/Console/Kernel.php. Both syntaxes work, but the new structure is recommended on recent versions. Sub-minute frequencies also work in these versions, but mind how schedule:run behaves during the minute.
Wrap-up
Debug the Scheduler layer by layer: first confirm the tasks are registered (schedule:list), then confirm the cron daemon and the entry are correct (crontab -l and systemctl status cron), and only then dig into Laravel's silent skips (mutex, timezone, sub-minute frequencies). In most cases, fixing the PHP path or clearing a stale mutex solves the whole problem.
If you have a Laravel project whose tasks refuse to run on time, tell the Captain Code team through the contact page, or start debugging yourself with Nyx first.