laravel/framework · error · RuntimeException

Queue resolver did not return a Queue implementation.

Error message

Queue resolver did not return a Queue implementation.

What it means

Dispatcher::dispatchToQueue resolves the queue implementation by invoking the queueResolver closure (bound by the BusServiceProvider) with the command's connection name. If that closure returns null or anything not implementing Illuminate\Contracts\Queue\Queue, dispatch cannot proceed. This is a container wiring / service provider failure rather than a per-job problem.

Solutions

1. Ensure Illuminate\Queue\QueueServiceProvider is registered in config/app.php (or bootstrap/app.php for Laravel 11+) alongside the BusServiceProvider.
2. Verify the 'queue' container binding resolves to an Illuminate\Queue\QueueManager instance: app('queue') instanceof QueueManager.
3. If using illuminate/bus standalone, register a queueResolver closure via the Dispatcher constructor or via Bus::dispatchUsingQueue($resolver) that returns a valid Queue.
4. Check for service provider overrides in bootstrap/app.php or custom Application subclasses that unbind 'queue'.

Example fix

// before (standalone illuminate/bus usage)
$dispatcher = new Dispatcher(new Container());
$dispatcher->dispatch(new SendInvoice($order)); // RuntimeException

// after
$container = new Container();
$container->instance('queue', new SyncQueue($container));
$dispatcher = new Dispatcher($container, fn ($c) => $container['queue']);
$dispatcher->dispatch(new SendInvoice($order));

// Validate the queue resolver returns a Queue before dispatching
$dispatcher = app(\Illuminate\Contracts\Bus\Dispatcher::class);
$resolved = app('queue');
if (! $resolved instanceof \Illuminate\Contracts\Queue\Queue) {
    throw new \RuntimeException('Container "queue" binding does not resolve to a Queue instance.');
}
$dispatcher->dispatch($command);

function queueResolverIsBound(\Illuminate\Container\Container $container): bool
{
    return $container->bound('queue')
        && $container->make('queue') instanceof \Illuminate\Contracts\Queue\Queue;
}

When it happens

Trigger: Calling Bus::dispatch($command) or dispatch($command) on a job implementing ShouldQueue when: the QueueServiceProvider is not registered, the container binding 'queue' was overridden or unbound, Bus::dispatchToQueue was invoked manually with a custom queueResolver returning null, or running outside a booted Laravel app (e.g., in a bare PHPUnit test bootstrapping only the Bus service provider).

Common situations: Using illuminate/bus as a standalone Composer dependency without illuminate/queue and the QueueServiceProvider. Testing a job via Bus::fake() replacement that was misconfigured. Overriding the 'queue' binding in a service provider with a factory that returns null on misconfiguration. App not fully booted in a long-running daemon (e.g., Laravel Octane reload race).

Related errors

• Attempted to batch job
• Session store requires session manager to be available in…
• To enable support for closure jobs, please install the…
• [ ] is aliased to itself.
• Circular alias reference for

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/069e3ed10b9d9141. Report an issue: GitHub.

Appendix: source

Thrown at src/Illuminate/Bus/Dispatcher.php:269

    /**
     * Dispatch a command to its appropriate handler behind a queue.
     *
     * @param  mixed  $command
     * @return mixed
     *
     * @throws \RuntimeException
     */
    public function dispatchToQueue($command)
    {
        $connection = $this->getAttributeValue($command, Connection::class, 'connection')
            ?? $this->resolveConnectionFromQueueRoute($command)
            ?? null;

        $queue = ($this->queueResolver)($connection);

        if (! $queue instanceof Queue) {
            throw new RuntimeException('Queue resolver did not return a Queue implementation.');
        }

        if (method_exists($command, 'queue')) {
            return $command->queue($queue, $command);
        }

        return $this->pushCommandToQueue($queue, $command);
    }

    /**
     * Push the command onto the given queue instance.
     *
     * @param  \Illuminate\Contracts\Queue\Queue  $queue
     * @param  mixed  $command
     * @return mixed
     */
    protected function pushCommandToQueue($queue, $command)
    {

View on GitHub (pinned to e0f6eb3518)