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

Thrown by Eloquent\Collection::getQueueableConnection() when models in the collection resolve to more than one database connection. When serializing a collection for the queue, Laravel records a single connection name to re-hydrate the query; models spread across connections (e.g. some on 'mysql', some on 'logging') make that impossible. The method compares each model's getConnectionName() against the first.

Solutions

Normalize all models to the same connection before queueing (e.g. ->setConnection('mysql') or rebuild via on()).
Group the collection by getConnectionName() and dispatch one job per connection group.
Avoid mixing results from different connections in a single collection that will be queued.
If accidental, inspect each model's $connection property and the models' getConnectionName() output.

Example fix

// before
$users = User::on('tenant')->get();
$admins = Admin::all(); // default connection
dispatch(new SyncUsers($users->concat($admins))); // LogicException

// after
$users->each(fn ($u) => $u->setConnection(config('database.default')));
dispatch(new SyncUsers($users->concat($admins)));

Defensive patterns

Strategy: validation

Validate before calling

$connections = $collection->map(fn ($m) => $m->getConnectionName())->unique();
if ($connections->count() > 1) {
    throw new \LogicException('Collection mixes connections: ' . $connections->implode(', '));
}
// safe to queue
dispatch(new SyncModels($collection));

Type guard

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

Try / catch

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

Prevention

Normalize models to one connection before queueing (setConnection()).
Avoid mixing Model::on('replica') results with default-connection models in a queued payload.
Document each model's $connection property so multi-database merges are intentional.

When it happens

Trigger: Queueing a collection where some models use the default connection and others have an explicit $connection property set, or were built via on('other-connection'). Occurs during job dispatch, queued notifications, or any serialization path that calls getQueueableConnection().

Common situations: Multi-tenant or multi-database setups where some models come from a tenant connection; merging models that have different $connection declarations; using Model::on() to read from a replica and then mixing those results with primary-connection models.

Related errors

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

Appendix: 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 e0f6eb3518)