laravel/framework · error · RuntimeException

Cache driver not available. Scheduling unique jobs not suppo

Error message

Cache driver not available. Scheduling unique jobs not supported.

What it means

Thrown by Schedule::dispatchUniqueJobToQueue() (src/Illuminate/Console/Scheduling/Schedule.php:280) when a scheduled job implementing ShouldBeUnique is dispatched but no Cache\Repository is bound in the container. Unique locking relies on the cache to acquire a UniqueLock.

Source

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

        $this->getDispatcher()->dispatch(
            $job->onConnection($connection)->onQueue($queue)
        );
    }

    /**
     * Dispatch the given unique job to the queue.
     *
     * @param  object  $job
     * @param  string|null  $queue
     * @param  string|null  $connection
     * @return void
     *
     * @throws \RuntimeException
     */
    protected function dispatchUniqueJobToQueue($job, $queue, $connection)
    {
        if (! Container::getInstance()->bound(Cache::class)) {
            throw new RuntimeException('Cache driver not available. Scheduling unique jobs not supported.');
        }

        if (! (new UniqueLock(Container::getInstance()->make(Cache::class)))->acquire($job)) {
            return;
        }

        $this->getDispatcher()->dispatch(
            $job->onConnection($connection)->onQueue($queue)
        );
    }

    /**
     * Dispatch the given job right now.
     *
     * @param  object  $job
     * @return void
     */
    protected function dispatchNow($job)

View on GitHub (pinned to bd6b5437e6)

Solutions

Ensure config/cache.php exists and CACHE_DRIVER/STORE is set to a valid store (redis, database, file).
Bind a cache repository in the container: $container->instance(\Illuminate\Contracts\Cache\Repository::class, $cacheRepo).
Remove ShouldBeUnique from the job if uniqueness is not required.
Run php artisan config:cache after fixing cache config.

Example fix

// before
// .env -> CACHE_STORE=null
$schedule->job(SyncUniqueJob::class)->hourly();  // SyncUniqueJob implements ShouldBeUnique

// after
// .env -> CACHE_STORE=redis
$schedule->job(SyncUniqueJob::class)->hourly();

Defensive patterns

Strategy: validation

Validate before calling

if (! \Illuminate\Container\Container::getInstance()->bound(\Illuminate\Contracts\Cache\Repository::class)) {
    // bind a cache store or drop ShouldBeUnique
}

Type guard

function cacheBound(): bool
{
    return \Illuminate\Container\Container::getInstance()->bound(\Illuminate\Contracts\Cache\Repository::class);
}

Try / catch

try {
    $schedule->job(UniqueJob::class)->hourly();
} catch (\RuntimeException $e) {
    // fall back to non-unique dispatch or fail loudly
}

Prevention

Configure a real CACHE_STORE (redis/database/file) for unique jobs.
Bind \Illuminate\Contracts\Cache\Repository explicitly in non-Laravel boots.
Don't mark jobs ShouldBeUnique unless a cache is reliably available.

When it happens

Trigger: Schedule::job(MyUniqueJob::class) where MyUniqueJob implements ShouldBeUnique, in an app where the cache is not bound (config/cache.php missing, or running outside Laravel with only illuminate/bus/console and no cache binding).

Common situations: Custom cache driver misconfiguration (CACHE_DRIVER=array/null), disabled cache in test/bootstrap, or a standalone Laravel subset without illuminate/cache bound.

Related errors

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