laravel/framework · error · LogicException

A scheduled event name is required to only run on one server

Error message

A scheduled event name is required to only run on one server. Use the 'name' method before 'onOneServer'.

What it means

Thrown by CallbackEvent::onOneServer() (src/Illuminate/Console/Scheduling/CallbackEvent.php:159) when $this->description is unset. Single-server coordination uses a scheduling mutex keyed off the event's description/name, so a nameless closure has no stable key.

Source

Thrown at src/Illuminate/Console/Scheduling/CallbackEvent.php:159

            throw new LogicException(
                "A scheduled event name is required to prevent overlapping. Use the 'name' method before 'withoutOverlapping'."
            );
        }

        return parent::withoutOverlapping($expiresAt, $releaseOnTerminationSignals);
    }

    /**
     * Allow the event to only run on one server for each cron expression.
     *
     * @return $this
     *
     * @throws \LogicException
     */
    public function onOneServer()
    {
        if (! isset($this->description)) {
            throw new LogicException(
                "A scheduled event name is required to only run on one server. Use the 'name' method before 'onOneServer'."
            );
        }

        return parent::onOneServer();
    }

    /**
     * Get the summary of the event for display.
     *
     * @return string
     */
    public function getSummaryForDisplay()
    {
        if (is_string($this->description)) {
            return $this->description;
        }

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Call ->name('unique-label') before ->onOneServer().
2. Ensure the cache store used for the scheduling mutex is shared across servers (redis/database).
3. Prefer scheduling a named command/job when you need single-server semantics.
4. Confirm the onOneServer feature is enabled per the docs (useCache() / schedule:cache).

Example fix

// before
$schedule->call(fn () => rotateLogs())
    ->hourly()
    ->onOneServer();

// after
$schedule->call(fn () => rotateLogs())
    ->name('log-rotation')
    ->hourly()
    ->onOneServer();

if ($event instanceof \Illuminate\Console\Scheduling\CallbackEvent && ! isset($event->description)) {
    // call name('...') before onOneServer()
}

// mirror of [89]: stable name presence is the precondition
$hasName = isset($event->description);

try {
    $event->onOneServer();
} catch (\LogicException $e) {
    $event->name('auto-' . uniqid())->onOneServer();
}

When it happens

Trigger: Calling $schedule->call(fn ())->hourly()->onOneServer() (or ->withoutOverlapping()->onOneServer()) without ->name('...').

Common situations: Enabling onOneServer() cluster-wide without naming the closure, or copying a command-style schedule onto a closure.

Related errors

• A scheduled event name is required to prevent overlapping. U
• Invalid scheduled callback event. Must be a string or callab
• Scheduled closures can not be run in the background.
• The seconds [$seconds] must be greater than zero.
• The seconds [$seconds] are not evenly divisible by 60.

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/fbc87b6e388b20e0.json. Report an issue: GitHub.