{"record":{"id":"97ff92318be25a65","repo":"mongodb/laravel-mongodb","slug":"aggregation-builder-requires-package-mongodb-builder-0-2","errorCode":null,"errorMessage":"Aggregation builder requires package mongodb/builder 0.2+","messagePattern":"Aggregation builder requires package mongodb/builder 0\\.2\\+","errorType":"exception","errorClass":"BadMethodCallException","httpStatus":null,"severity":"error","filePath":"src/Query/Builder.php","lineNumber":578,"sourceCode":"            'orders' => $this->orders,\n            'offset' => $this->offset,\n            'limit' => $this->limit,\n            'aggregate' => $this->aggregate,\n        ];\n\n        return md5(serialize(array_values($key)));\n    }\n\n    /** @return ($function is null ? AggregationBuilder : mixed) */\n    #[Override]\n    public function aggregate($function = null, $columns = ['*'])\n    {\n        assert(is_array($columns), new TypeError(sprintf('Argument #2 ($columns) must be of type array, %s given', get_debug_type($columns))));\n\n        if ($function === null) {\n            if (! trait_exists(FluentFactoryTrait::class)) {\n                // This error will be unreachable when the mongodb/builder package will be merged into mongodb/mongodb\n                throw new BadMethodCallException('Aggregation builder requires package mongodb/builder 0.2+');\n            }\n\n            if ($columns !== ['*']) {\n                throw new InvalidArgumentException('Columns cannot be specified to create an aggregation builder. Add a $project stage instead.');\n            }\n\n            if ($this->wheres) {\n                throw new BadMethodCallException('Aggregation builder does not support previous query-builder instructions. Use a $match stage instead.');\n            }\n\n            return new AggregationBuilder($this->collection, $this->options);\n        }\n\n        $this->aggregate = [\n            'function' => $function,\n            'columns' => $columns,\n        ];\n","sourceCodeStart":560,"sourceCodeEnd":596,"githubUrl":"https://github.com/mongodb/laravel-mongodb/blob/0634653039468ceb0268a69192bdac64469ed043/src/Query/Builder.php#L560-L596","documentation":"Builder::aggregate() can return a fluent AggregationBuilder (from mongodb/builder) when no function is given. That builder requires the FluentFactoryTrait from mongodb/builder 0.2+; if the trait class does not exist, this BadMethodCallException is thrown, noting the package will later merge into mongodb/mongodb.","triggerScenarios":"Calling ->aggregate() with no aggregation function (null $function) to obtain an AggregationBuilder while mongodb/builder is absent or older than 0.2.","commonSituations":"Projects using only mongodb/mongodb without the separate mongodb/builder package, or a composer.lock pinned to a pre-0.2 builder.","solutions":["Run: composer require mongodb/builder:^0.2","Alternatively call ->aggregate('count'/'avg'/...) with an explicit function instead of the fluent builder.","Upgrade mongodb/mongodb and mongodb/builder together to compatible versions."],"exampleFix":"// before\ncomposer require mongodb/mongodb  # builder missing\n// after\ncomposer require mongodb/mongodb mongodb/builder:^0.2","handlingStrategy":"validation","validationCode":"if (! trait_exists(MongoDB\\Builder\\FluentFactoryTrait::class)) {\n    throw new RuntimeException('composer require mongodb/builder:^0.2 for aggregation builder');\n}\n$agg = Model::aggregate(null);","typeGuard":"function aggregationBuilderAvailable(): bool { return trait_exists(MongoDB\\Builder\\FluentFactoryTrait::class); }","tryCatchPattern":"try {\n    $agg = Model::aggregate(null);\n} catch (BadMethodCallException $e) {\n    if (str_contains($e->getMessage(), 'mongodb/builder')) {\n        // fall back to function-based aggregation\n        $agg = Model::aggregate('count');\n    } else { throw $e; }\n}","preventionTips":["Require mongodb/builder ^0.2 explicitly in composer.json","Pin compatible versions of mongodb/mongodb and mongodb/builder","Check composer.lock in CI for the builder package","Use function-based aggregate() calls if the fluent builder is optional"],"tags":["aggregation","composer","version"],"backgroundTag":"missing-optional-dependency","analyzedSha":"0634653039468ceb0268a69192bdac64469ed043","analyzedAt":"2026-09-15T02:56:37.067Z","contentChangedAt":"2026-09-15T02:56:37.067Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}