{"id":"dc39252a2d8e8ea1","repo":"laravel/framework","slug":"count-items-were-found","errorCode":null,"errorMessage":"$count items were found.","messagePattern":"\\$count items were found\\.","errorType":"exception","errorClass":"MultipleItemsFoundException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Collections/Arr.php","lineNumber":1098,"sourceCode":"     * @param  (callable(mixed, array-key): array)|null  $callback\n     *\n     * @throws \\Illuminate\\Support\\ItemNotFoundException\n     * @throws \\Illuminate\\Support\\MultipleItemsFoundException\n     */\n    public static function sole($array, ?callable $callback = null)\n    {\n        if ($callback) {\n            $array = static::where($array, $callback);\n        }\n\n        $count = count($array);\n\n        if ($count === 0) {\n            throw new ItemNotFoundException;\n        }\n\n        if ($count > 1) {\n            throw new MultipleItemsFoundException($count);\n        }\n\n        return static::first($array);\n    }\n\n    /**\n     * Sort the array using the given callback or \"dot\" notation.\n     *\n     * @template TKey of array-key\n     * @template TValue\n     *\n     * @param  iterable<TKey, TValue>  $array\n     * @param  callable|string|null|array<int, (callable(TValue, TValue): -1|0|1)|array{string, SortDirection|'asc'|'desc'}>  $callback\n     * @return array<TKey, TValue>\n     */\n    public static function sort($array, $callback = null)\n    {\n        return (new Collection($array))->sortBy($callback)->all();","sourceCodeStart":1080,"sourceCodeEnd":1116,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Collections/Arr.php#L1080-L1116","documentation":"Thrown by Arr::sole() (via MultipleItemsFoundException) when more than one item remains after applying the optional callback. sole() is the 'expect exactly one' accessor: zero items raises ItemNotFound, two or more raises this. The message reports how many were found.","triggerScenarios":"Calling Arr::sole($users) on a multi-element array, or Arr::sole($users, fn ($u) => $u->active) when several users match the predicate.","commonSituations":"Querying by a key that is supposedly unique but the dataset has duplicates; loose predicates (e.g. fn => true); a collection that was expected to be filtered down to one but wasn't.","solutions":["Tighten the predicate so only one element matches (filter by a unique identifier).","Use Arr::first() if you don't actually need uniqueness.","De-duplicate the source before calling sole().","Guard: if (count($matches) !== 1) handle the ambiguous case explicitly."],"exampleFix":"// before\n$user = Arr::sole($users, fn ($u) => $u->team_id === $teamId);\n\n// after\n$user = Arr::sole($users, fn ($u) => $u->id === $expectedId);\n// or accept any match\n$user = Arr::first($users, fn ($u) => $u->team_id === $teamId);","handlingStrategy":"validation","validationCode":"$matches = array_values(array_filter($users, $callback ?? fn () => true));\nif (count($matches) !== 1) {\n    // handle ambiguity explicitly instead of calling Arr::sole()\n}","typeGuard":"function hasExactlyOne(array $array, ?callable $cb = null): bool {\n    return count($cb ? array_filter($array, $cb) : $array) === 1;\n}","tryCatchPattern":"try {\n    $user = Arr::sole($users, fn ($u) => $u->team_id === $teamId);\n} catch (\\Illuminate\\Collections\\MultipleItemsFoundException $e) {\n    // narrow the predicate or take the first match\n    $user = Arr::first($users, fn ($u) => $u->id === $id);\n} catch (\\Illuminate\\Collections\\ItemNotFoundException $e) {\n    $user = null;\n}","preventionTips":["Use Arr::sole() only with predicates that are unique by construction (e.g. a primary key).","Prefer Arr::first() when duplicates are tolerable.","De-duplicate the source before calling sole()."],"tags":["collections","arrays","validation","laravel"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}