mongodb/laravel-mongodb · error · InvalidArgumentException

Aggregating by group requires zero or one columns.

Error message

Aggregating by group requires zero or one columns.

What it means

aggregateByGroup implements Laravel's group-wise aggregation on MongoDB by wrapping the aggregate call in a single group stage, so the MongoDB pipeline can only handle zero or one column; more than one column cannot be mapped to the pipeline and triggers this InvalidArgumentException. Callers like count/avg-per-group with a single column work; passing multiple columns does not.

Solutions

1. Pass a single column: aggregateByGroup('avg', ['price']).
2. Call aggregateByGroup once per aggregated field.
3. Or build the group pipeline manually with aggregateRaw()/addRawStage('$group', ...) to combine multiple accumulators.

Example fix

// before
->groupBy('category')->aggregateByGroup('avg', ['price', 'qty']);
// after
->groupBy('category')->aggregateByGroup('avg', ['price']);

if (is_array($columns) && count($columns) > 1) {
    throw new InvalidArgumentException('aggregateByGroup accepts at most one column');
}
$query->groupBy($group)->aggregateByGroup($fn, $columns);

try {
    $value = $query->groupBy('category')->aggregateByGroup('avg', $cols);
} catch (InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'zero or one columns')) {
        $value = $query->groupBy('category')->aggregateByGroup('avg', [$cols[0]]);
    } else { throw $e; }
}

When it happens

Trigger: Calling ->groupBy('category')->aggregateByGroup('avg', ['price', 'quantity']) — count($columns) > 1.

Common situations: Developers trying to aggregate several fields at once per group, e.g. avg price and sum quantity in a single call.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Columns cannot be specified to create an aggregation…
• The stage name " " is invalid. It must start with a "$"…
• Query not compatible with cursor
• Aggregation builder requires package mongodb/builder 0.2+
• Aggregation builder does not support previous query-builder…

AI-assisted analysis of mongodb/laravel-mongodb@0634653039 (2026-09-15). Data as JSON: /api/errors/bbb8ddfcb6db1bd4. Report an issue: GitHub.

Appendix: source

Thrown at src/Query/Builder.php:640

        }

        if (isset($results[0])) {
            $result = (array) $results[0];

            return $result['aggregate'];
        }
    }

    /**
     * @param string $function
     * @param array  $columns
     *
     * @return mixed
     */
    public function aggregateByGroup(string $function, array $columns = ['*'])
    {
        if (count($columns) > 1) {
            throw new InvalidArgumentException('Aggregating by group requires zero or one columns.');
        }

        return $this->aggregate($function, $columns);
    }

    /** @inheritdoc */
    #[Override]
    public function exists()
    {
        return $this->first(['id']) !== null;
    }

    /** @inheritdoc */
    public function distinct($column = false)
    {
        $this->distinct = true;

        if ($column) {

View on GitHub (pinned to 0634653039)