laravel/framework · error · RuntimeException

Unable to resolve the dispatcher from the service container.

Error message

Unable to resolve the dispatcher from the service container. Please bind it or install the illuminate/bus package.

What it means

Thrown by Schedule::getDispatcher() (src/Illuminate/Console/Scheduling/Schedule.php:496) when Container::getInstance()->make(Dispatcher::class) raises BindingResolutionException. Scheduled jobs need an illuminate/bus Dispatcher to send ShouldQueue jobs; without it the chain catches and re-throws a clearer message.

Source

Thrown at src/Illuminate/Console/Scheduling/Schedule.php:496

        }

        return $this;
    }

    /**
     * Get the job dispatcher, if available.
     *
     * @return \Illuminate\Contracts\Bus\Dispatcher
     *
     * @throws \RuntimeException
     */
    protected function getDispatcher()
    {
        if ($this->dispatcher === null) {
            try {
                $this->dispatcher = Container::getInstance()->make(Dispatcher::class);
            } catch (BindingResolutionException $e) {
                throw new RuntimeException(
                    'Unable to resolve the dispatcher from the service container. Please bind it or install the illuminate/bus package.',
                    is_int($e->getCode()) ? $e->getCode() : 0, $e
                );
            }
        }

        return $this->dispatcher;
    }

    /**
     * Indicate that the scheduler should not poll for pause or interrupt signals.
     *
     * This prevents the scheduler from hitting the application cache to determine if it needs to pause or interrupt.
     *
     * @return void
     */
    public static function withoutInterruptionPolling()
    {

View on GitHub (pinned to bd6b5437e6)

Solutions

composer require illuminate/bus.
Register Illuminate\Bus\BusServiceProvider (or register the Dispatcher binding manually).
If queueing isn't needed, run jobs synchronously by ensuring they do not implement ShouldQueue.
Re-run composer dump-autoload after installing.

Example fix

// before
// composer.json omits illuminate/bus
$schedule->job(SyncJob::class)->hourly();  // SyncJob implements ShouldQueue

// after
// composer require illuminate/bus
// bootstrap: $app->register(Illuminate\Bus\BusServiceProvider::class);
$schedule->job(SyncJob::class)->hourly();

Defensive patterns

Strategy: validation

Validate before calling

if (! \Illuminate\Container\Container::getInstance()->bound(\Illuminate\Contracts\Bus\Dispatcher::class)) {
    // install illuminate/bus or bind the dispatcher before scheduling queued jobs
}

Type guard

function dispatcherBound(): bool
{
    return \Illuminate\Container\Container::getInstance()->bound(\Illuminate\Contracts\Bus\Dispatcher::class);
}

Try / catch

try {
    $schedule->job(QueuedJob::class)->hourly();
} catch (\RuntimeException $e) {
    // install illuminate/bus, register BusServiceProvider, then retry
}

Prevention

Register Illuminate\Bus\BusServiceProvider in your bootstrap.
Verify dispatcher binding in a boot-time health check.
Don't schedule ShouldQueue jobs without a bound bus dispatcher.

When it happens

Trigger: Schedule::job(SomeJob) (a queued job) in a project where the bus dispatcher isn't bound. Common with minimal illuminate/console + illuminate/queue setups that omit illuminate/bus, or where BusServiceProvider wasn't registered.

Common situations: Sub-framework setups, custom service providers that forget to register Illuminate\Bus\BusServiceProvider, or removed illuminate/bus from composer.json.

Related errors

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