{"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/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Database/Concerns/BuildsQueries.php#L389-L425","documentation":"Thrown by Builder::sole() when the query returns more than one row. sole() asserts the result set is exactly one record and raises MultipleRecordsFoundException (carrying the $count) when the count exceeds 1, so callers can detect uniqueness violations instead of silently picking the first.","triggerScenarios":"User::where('email', $email)->sole() where the email column is not unique and two rows match; looking up by a field you believed unique; race condition inserting a duplicate between check and use.","commonSituations":"Missing unique index on a column queried via sole(); data migration that created duplicates; querying by a non-unique attribute (name, status) where multiple rows legitimately match; soft-deleted duplicates.","solutions":["Add a unique database index/constraint on the column you query via sole().","Use firstOrFail() if you only need one row and duplicates are tolerable.","Catch Illuminate\\Database\\MultipleRecordsFoundException to handle the violation explicitly.","Narrow the query (->latest()->sole() etc.) or deduplicate the data first."],"exampleFix":"// before\n$license = License::where('key', $key)->sole();\n// throws when two rows share the key\n\n// after\n// 1. add unique index: $table->string('key')->unique();\n// 2. handle gracefully:\nuse Illuminate\\Database\\MultipleRecordsFoundException;\ntry {\n    $license = License::where('key', $key)->sole();\n} catch (MultipleRecordsFoundException $e) {\n    abort(409, 'Duplicate license key: '.$e->count.' found.');\n}","handlingStrategy":"try-catch","validationCode":"$count = Model::where('key', $key)->count();\nif ($count > 1) {\n    throw new \\RuntimeException(\"{$count} duplicates found\");\n}","typeGuard":"function isUnique(\\Illuminate\\Database\\Eloquent\\Builder $q): bool { return $q->count() <= 1; }","tryCatchPattern":"use Illuminate\\Database\\MultipleRecordsFoundException;\ntry {\n    $rec = Model::where('key', $key)->sole();\n} catch (MultipleRecordsFoundException $e) {\n    abort(409, \"{$e->count} records found\");\n}","preventionTips":["Add unique indexes on columns queried via sole().","Use firstOrFail when duplicates are tolerable.","Catch MultipleRecordsFoundException for explicit handling."],"tags":["database","eloquent","uniqueness","query-builder"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}