laravel/framework · error · LogicException

Queueing collections with multiple model connections is not

Error message

Queueing collections with multiple model connections is not supported.

What it means

Collection::getQueueableConnection() walks every model and requires they all report the same connection name. This matters because the queue restoration uses a single connection name; mixed connections would silently restore from the wrong database.

Source

Thrown at src/Illuminate/Database/Eloquent/Collection.php:916

    /**
     * Get the connection of the entities being queued.
     *
     * @return string|null
     *
     * @throws \LogicException
     */
    public function getQueueableConnection()
    {
        if ($this->isEmpty()) {
            return;
        }

        $connection = $this->first()->getConnectionName();

        $this->each(function ($model) use ($connection) {
            if ($model->getConnectionName() !== $connection) {
                throw new LogicException('Queueing collections with multiple model connections is not supported.');
            }
        });

        return $connection;
    }

    /**
     * Get the Eloquent query builder from the collection.
     *
     * @return \Illuminate\Database\Eloquent\Builder<TModel>
     *
     * @throws \LogicException
     */
    public function toQuery()
    {
        $model = $this->first();

        if (! $model) {

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Normalize the connection before queueing: $models->each->setConnection($conn).
2. Dispatch separate jobs per connection group: $models->groupBy(fn ($m) => $m->getConnectionName()).
3. Pass identifiers (IDs + class + connection) and re-resolve inside the job handler.

Example fix

// before
SyncRecords::dispatch($records); // records span 'mysql' and 'pgsql'

// after
$records->groupBy(fn ($m) => $m->getConnectionName())
    ->each(fn ($group, $conn) => SyncRecords::dispatch($group));

$conns = $collection->map(fn ($m) => $m->getConnectionName())->unique();
if ($conns->count() > 1) {
    throw new \LogicException('Mixed connections: ' . $conns->implode(','));
}

function sharesOneConnection(\Illuminate\Database\Eloquent\Collection $c): bool
{
    return $c->map(fn ($m) => $m->getConnectionName())->unique()->count() <= 1;
}

try {
    $job = CloneThis::dispatch($collection);
} catch (\LogicException $e) {
    if (str_contains($e->getMessage(), 'multiple model connections')) {
        $collection->groupBy(fn ($m) => $m->getConnectionName())
            ->each(fn ($group) => CloneThis::dispatch($group));
    } else {
        throw $e;
    }
}

When it happens

Trigger: Queueing a collection whose models live on different database connections, e.g. collect([$userOnMysql, $userOnPgsql]) passed to a queued job, or a multi-tenant setup where some models were explicitly ->on('tenant_a') before being collected.

Common situations: Multi-database or read/write split setups; models reassigned with ->setConnection() or ->on(); merging results from read-replica and primary; sharding where models share a class but differ by connection.

Related errors

• Queueing collections with multiple model types is not suppor
• Queueable entity [%s] not found for ID [%s].
• The provided class must extend [{Collection::class}].
• The provided class must extend [{Collection::class}].
• Unable to create query for empty collection.

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