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

Bus\Dispatcher::dispatchToQueue() invokes the queueResolver closure to obtain a Queue implementation for the job's connection; if the returned value is not an instance of Illuminate\Contracts\Queue\Queue it throws this RuntimeException. It guards against a misconfigured or missing queue manager binding.

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 bd6b5437e6)

Solutions

Install and register illuminate/queue (require the package and run QueueServiceProvider) so the resolver returns a Queue instance.
If running the full Laravel framework, ensure the QueueServiceProvider is registered in config/app.php and not removed.
Check that the queue connection (QUEUE_CONNECTION) in config/queue.php resolves to a real driver (sync/database/redis/etc.).
If building a custom container binding, ensure the 'queue' binding returns an object implementing Illuminate\Contracts\Queue\Queue.

Example fix

// before (standalone, queue not wired)
$dispatcher = new \Illuminate\Bus\Dispatcher($container);
$dispatcher->dispatch(new ShouldQueueJob());

// after
use Illuminate\Queue\QueueServiceProvider;
(new QueueServiceProvider($app))->register();
$dispatcher = new \Illuminate\Bus\Dispatcher($app, function ($connection) use ($app) {
    return $app['queue']->connection($connection);
});

Defensive patterns

Strategy: validation

Validate before calling

if (! app()->bound('queue') || ! app('queue') instanceof \Illuminate\Contracts\Queue\Queue) {
    throw new \RuntimeException('Queue manager not bound; cannot dispatch queued jobs.');
}
// or check the package
if (! class_exists(\Illuminate\Queue\CallQueuedClosure::class)) {
    throw new \RuntimeException('illuminate/queue is required for queued jobs.');
}

Type guard

function queueIsConfigured(): bool
{
    return app()->bound('queue')
        && interface_exists(\Illuminate\Contracts\Queue\Queue::class)
        && config('queue.default') !== null;
}

Try / catch

try {
    $dispatcher->dispatch($command);
} catch (\RuntimeException $e) {
    if ($e->getMessage() === 'Queue resolver did not return a Queue implementation.') {
        // install/register illuminate/queue then retry
    }
    throw $e;
}

Prevention

Always pair illuminate/bus with illuminate/queue in composer.json.
Register QueueServiceProvider in service providers.
Assert QUEUE_CONNECTION is set in .env.example.
Test dispatch paths in CI to catch wiring regressions.

When it happens

Trigger: Dispatching a job that implements ShouldQueue when the queue resolver callback returns null or an invalid object. Occurs when the illuminate/queue package is not wired into the container, when a custom queue resolver was mis-set, or in a minimal (non-Framework) Illuminate install without QueueServiceProvider.

Common situations: Using illuminate/bus standalone without illuminate/queue installed/registered. A test or console kernel that does not boot the QueueServiceProvider. Manually constructing a Bus\Dispatcher with a broken queueResolver closure.

Related errors

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