{"record":{"id":"b01aa82089049e03","repo":"laravel/framework","slug":"count-records-were-found","errorCode":null,"errorMessage":"$count records were found.","messagePattern":"\\$count records were found\\.","errorType":"exception","errorClass":"MultipleRecordsFoundException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Concerns/BuildsQueries.php","lineNumber":407,"sourceCode":"     *\n     * @param  array|string  $columns\n     * @return TValue\n     *\n     * @throws \\Illuminate\\Database\\RecordsNotFoundException\n     * @throws \\Illuminate\\Database\\MultipleRecordsFoundException\n     */\n    public function sole($columns = ['*'])\n    {\n        $result = $this->limit(2)->get($columns);\n\n        $count = $result->count();\n\n        if ($count === 0) {\n            throw new RecordsNotFoundException;\n        }\n\n        if ($count > 1) {\n            throw new MultipleRecordsFoundException($count);\n        }\n\n        return $result->first();\n    }\n\n    /**\n     * Paginate the given query using a cursor paginator.\n     *\n     * @param  int  $perPage\n     * @param  array|string  $columns\n     * @param  string  $cursorName\n     * @param  \\Illuminate\\Pagination\\Cursor|string|null  $cursor\n     * @return \\Illuminate\\Contracts\\Pagination\\CursorPaginator\n     */\n    protected function paginateUsingCursor($perPage, $columns = ['*'], $cursorName = 'cursor', $cursor = null)\n    {\n        if (! $cursor instanceof Cursor) {\n            $cursor = is_string($cursor)","sourceCodeStart":389,"sourceCodeEnd":425,"githubUrl":"https://github.com/laravel/framework/blob/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Concerns/BuildsQueries.php#L389-L425","documentation":"MultipleRecordsFoundException (RuntimeException) from sole() when the query returns more than one row. sole() is meant to fetch exactly one record; it limits to 2 rows and throws if it gets 2, surfacing the count so callers know the query was not selective enough.","triggerScenarios":"Model::where('email', $e)->sole() when duplicate emails exist; sole() on a query missing a uniqueness guarantee; lookup by a non-unique column expecting a single match.","commonSituations":"Data-integrity drift (duplicate rows that should be unique); soft-deletes causing two rows (one deleted, one live) when only live was expected; missing where clause; race insert creating a duplicate.","solutions":["Add a uniqueness constraint/migration on the column you query by.","Tighten the query with additional where conditions so only one row matches.","If duplicates are expected, use first() instead of sole().","Clean up duplicate rows and add a unique index to prevent recurrence."],"exampleFix":"// before\n$user = User::where('email', $email)->sole(); // >1 rows\n// after\n$user = User::where('email', $email)->sole(); // plus migration:\n// Schema::table('users', fn ($t) => $t->unique('email'));\n// or, if duplicates are acceptable:\n$user = User::where('email', $email)->first();","handlingStrategy":"validation","validationCode":"// Before sole(), assert the query yields exactly one row.\n$count = Model::where('email', $email)->count();\nif ($count !== 1) {\n    throw new RuntimeException(\"Expected exactly 1 row for email [$email], found $count.\");\n}\n$user = Model::where('email', $email)->sole();","typeGuard":"function queryYieldsSingle(\\Illuminate\\Database\\Eloquent\\Builder $q): bool\n{\n    return $q->count() === 1;\n}","tryCatchPattern":"use Illuminate\\Database\\MultipleRecordsFoundException;\nuse Illuminate\\Database\\RecordsNotFoundException;\n\ntry {\n    $user = Model::where('email', $email)->sole();\n} catch (MultipleRecordsFoundException $e) {\n    // deduplicate rows, tighten the query, or fall back to first()\n} catch (RecordsNotFoundException $e) {\n    abort(404);\n}","preventionTips":["Enforce uniqueness with a DB unique index on columns used with sole().","Add where conditions sufficient to guarantee a single match.","Reserve sole() for invariants you expect the schema to guarantee."],"tags":["database","query-builder","eloquent","data-integrity"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}