The Problem: Duplicate Scheduled Tasks Across Servers
When you run schedule:run on more than one server, every scheduled task fires once per server. Clearing a local cache is fine that way, but sending a daily report email three times is not. Laravel has long offered onOneServer() to take a cache lock and let only the first server run a given task, but you had to remember to add it to every single task definition.
Laravel 13.35 ships two improvements that make multi-server scheduling much easier to manage.
Schedule::alwaysOnOneServer()
Contributed by Jack Bayliss, Schedule::alwaysOnOneServer() applies the one-server constraint to every task in the schedule automatically. Call it once in your service provider:
// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Schedule;
public function boot(): void
{
Schedule::alwaysOnOneServer();
}
The flag is evaluated when the schedule reads its events, so tasks defined later in routes/console.php are covered too. It is off by default, and Schedule::alwaysOnOneServer(false) disables it again.
Name Your Closure Tasks
The lock key is built from the task name. Artisan command tasks have a name automatically; closure tasks only have one if you call ->name(). Without a name, alwaysOnOneServer() silently skips the closure and it runs on every server:
// Runs on every server - no name
Schedule::call(fn () => Report::sendDaily())->daily();
// Runs on one server - name provided
Schedule::call(fn () => Report::sendDaily())
->name('send-daily-report')
->daily();
There is no warning when a closure is skipped, so audit your schedule for unnamed closures before enabling the flag.
Shared Cache Is Required
The lock lives in the cache. Every server must point at the same cache store such as Redis, Memcached, DynamoDB, or the database. The file and array drivers are local to each server and will not work.
If your default cache store is local, point the scheduler at a shared store with Schedule::useCache():
public function boot(): void
{
Schedule::alwaysOnOneServer();
Schedule::useCache('redis');
}
useCache() only affects scheduler locks; the rest of your application keeps its default store.
If some tasks genuinely need to run on every server, leave alwaysOnOneServer() off and call ->onOneServer() only on the tasks that should run once.
Schedule::hasBeenInterruptedSince()
Before 13.35, php artisan schedule:interrupt set a flag that only schedule:run checked. A command started with runInBackground() ran in its own process and never saw the flag, so it kept running on old code through a deploy.
Contributed by cyppe, the new approach stores the time of the interrupt, mirroring how queue:restart works. A long-running command can now poll that time against its own start time and stop gracefully between batches:
use Illuminate\Console\Command;
use Illuminate\Console\Scheduling\Schedule;
class SyncInventory extends Command
{
protected $signature = 'inventory:sync';
public function handle(Schedule $schedule): int
{
$startedAt = now();
foreach (Product::lazyById(500) as $product) {
if ($schedule->hasBeenInterruptedSince($startedAt)) {
$this->info('Interrupted by a deploy, stopping.');
return self::SUCCESS;
}
$this->syncProduct($product);
}
return self::SUCCESS;
}
}
hasBeenInterruptedSince() returns true only for an interrupt that occurred at or after the time you pass in, so a stale interrupt from an earlier deploy will not stop a fresh run.
A typical deploy script now looks like:
php artisan schedule:interrupt
php artisan queue:restart
The interrupt time is stored in the default cache store, not the one passed to useCache(). That default store must be shared across servers. Calling Schedule::withoutInterruptionPolling() disables polling, causing hasBeenInterruptedSince() to always return false.
Key Takeaways
- Schedule::alwaysOnOneServer() replaces per-task ->onOneServer() calls with a single global setting.
- Closure tasks must have a ->name() to be covered; unnamed closures are silently skipped.
- A shared cache store such as Redis or the database is mandatory for any one-server locking to work.
- Schedule::useCache('redis') scopes the shared store to scheduler locks only.
- Schedule::hasBeenInterruptedSince() lets background commands stop cleanly on deploy.
- The interrupt timestamp approach matches queue:restart, making deploy scripts consistent.