{"id":"fbc87b6e388b20e0","repo":"laravel/framework","slug":"a-scheduled-event-name-is-required-to-only-run-on","errorCode":null,"errorMessage":"A scheduled event name is required to only run on one server. Use the 'name' method before 'onOneServer'.","messagePattern":"A scheduled event name is required to only run on one server\\. Use the 'name' method before 'onOneServer'\\.","errorType":"exception","errorClass":"LogicException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Console/Scheduling/CallbackEvent.php","lineNumber":159,"sourceCode":"            throw new LogicException(\n                \"A scheduled event name is required to prevent overlapping. Use the 'name' method before 'withoutOverlapping'.\"\n            );\n        }\n\n        return parent::withoutOverlapping($expiresAt, $releaseOnTerminationSignals);\n    }\n\n    /**\n     * Allow the event to only run on one server for each cron expression.\n     *\n     * @return $this\n     *\n     * @throws \\LogicException\n     */\n    public function onOneServer()\n    {\n        if (! isset($this->description)) {\n            throw new LogicException(\n                \"A scheduled event name is required to only run on one server. Use the 'name' method before 'onOneServer'.\"\n            );\n        }\n\n        return parent::onOneServer();\n    }\n\n    /**\n     * Get the summary of the event for display.\n     *\n     * @return string\n     */\n    public function getSummaryForDisplay()\n    {\n        if (is_string($this->description)) {\n            return $this->description;\n        }\n","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Console/Scheduling/CallbackEvent.php#L141-L177","documentation":"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.","triggerScenarios":"Calling $schedule->call(fn ())->hourly()->onOneServer() (or ->withoutOverlapping()->onOneServer()) without ->name('...').","commonSituations":"Enabling onOneServer() cluster-wide without naming the closure, or copying a command-style schedule onto a closure.","solutions":["Call ->name('unique-label') before ->onOneServer().","Ensure the cache store used for the scheduling mutex is shared across servers (redis/database).","Prefer scheduling a named command/job when you need single-server semantics.","Confirm the onOneServer feature is enabled per the docs (useCache() / schedule:cache)."],"exampleFix":"// before\n$schedule->call(fn () => rotateLogs())\n    ->hourly()\n    ->onOneServer();\n\n// after\n$schedule->call(fn () => rotateLogs())\n    ->name('log-rotation')\n    ->hourly()\n    ->onOneServer();","handlingStrategy":"validation","validationCode":"if ($event instanceof \\Illuminate\\Console\\Scheduling\\CallbackEvent && ! isset($event->description)) {\n    // call name('...') before onOneServer()\n}","typeGuard":"// mirror of [89]: stable name presence is the precondition\n$hasName = isset($event->description);","tryCatchPattern":"try {\n    $event->onOneServer();\n} catch (\\LogicException $e) {\n    $event->name('auto-' . uniqid())->onOneServer();\n}","preventionTips":["Name all closure-based scheduled tasks when using cluster features.","Verify the scheduling mutex cache store is shared across servers.","Document per-task names in a central registry."],"tags":["scheduling","console","mutex","laravel"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}