{"record":{"id":"8ff89ed281c1bc34","repo":"laravel/framework","slug":"queueing-collections-with-multiple-model-connectio","errorCode":null,"errorMessage":"Queueing collections with multiple model connections is not supported.","messagePattern":"Queueing collections with multiple model connections is not supported\\.","errorType":"exception","errorClass":"LogicException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Eloquent/Collection.php","lineNumber":916,"sourceCode":"\n    /**\n     * Get the connection of the entities being queued.\n     *\n     * @return string|null\n     *\n     * @throws \\LogicException\n     */\n    public function getQueueableConnection()\n    {\n        if ($this->isEmpty()) {\n            return;\n        }\n\n        $connection = $this->first()->getConnectionName();\n\n        $this->each(function ($model) use ($connection) {\n            if ($model->getConnectionName() !== $connection) {\n                throw new LogicException('Queueing collections with multiple model connections is not supported.');\n            }\n        });\n\n        return $connection;\n    }\n\n    /**\n     * Get the Eloquent query builder from the collection.\n     *\n     * @return \\Illuminate\\Database\\Eloquent\\Builder<TModel>\n     *\n     * @throws \\LogicException\n     */\n    public function toQuery()\n    {\n        $model = $this->first();\n\n        if (! $model) {","sourceCodeStart":898,"sourceCodeEnd":934,"githubUrl":"https://github.com/laravel/framework/blob/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Eloquent/Collection.php#L898-L934","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","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."],"exampleFix":"// before\n$users = User::on('tenant')->get();\n$admins = Admin::all(); // default connection\ndispatch(new SyncUsers($users->concat($admins))); // LogicException\n\n// after\n$users->each(fn ($u) => $u->setConnection(config('database.default')));\ndispatch(new SyncUsers($users->concat($admins)));","handlingStrategy":"validation","validationCode":"$connections = $collection->map(fn ($m) => $m->getConnectionName())->unique();\nif ($connections->count() > 1) {\n    throw new \\LogicException('Collection mixes connections: ' . $connections->implode(', '));\n}\n// safe to queue\ndispatch(new SyncModels($collection));","typeGuard":"function containsSingleConnection(\\Illuminate\\Database\\Eloquent\\Collection $c): bool\n{\n    return $c->map(fn ($m) => $m->getConnectionName())->unique()->count() === 1;\n}","tryCatchPattern":"try {\n    dispatch(new SyncModels($collection));\n} catch (\\LogicException $e) {\n    if (str_contains($e->getMessage(), 'multiple model connections')) {\n        $collection->groupBy(fn ($m) => $m->getConnectionName())\n            ->each(fn ($group) => dispatch(new SyncModels($group)));\n    } else {\n        throw $e;\n    }\n}","preventionTips":["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."],"tags":["eloquent","collection","queue","multi-database","serialization"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}