mongodb/laravel-mongodb · error · InvalidArgumentException

Between $values must be a list with exactly two elements…

Error message

Between $values must be a list with exactly two elements: [min, max]

What it means

Thrown by whereBetween()/orWhereBetween() when the $values argument is not a flat list of exactly two elements. The MongoDB builder requires the literal [min, max] shape to build a {$gte: min, $lte: max} range filter; keyed arrays, arrays of 0/1/3+ elements, or non-list inputs are rejected.

Solutions

1. Pass a numerically-indexed array with exactly two values in [min, max] order, e.g. ->whereBetween('price', [10, 100]).
2. Use array_values($bounds) to strip string/associative keys before calling.
3. Ensure bounds-collection logic always yields exactly two entries (check count($values) === 2 before calling).
4. If only one bound is needed, use ->where('price', '>=', 10) or ->where('price', '<=', 100) instead.

Example fix

// before
$bounds = ['min' => 10, 'max' => 100];
$query->whereBetween('price', $bounds);
// after
$bounds = array_values(['min' => 10, 'max' => 100]); // [10, 100]
$query->whereBetween('price', $bounds);

if (!is_array($values) || !array_is_list($values) || count($values) !== 2) {
    throw new InvalidArgumentException('whereBetween expects [min, max]');
}
$query->whereBetween($column, $values);

When it happens

Trigger: Calling ->whereBetween('age', ['min' => 18, 'max' => 65]) (string keys, not a list), ->whereBetween('age', [18, 65, 99]) (3 elements), ->whereBetween('age', []) (0 elements), or passing a Collection whose ->all() is not a 2-element list.

Common situations: Building the range dynamically from config or request input where optional bounds result in fewer/more elements; PHP arrays with non-sequential keys after unset(); devs used to Laravel's SQL builder being lenient about array shape.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• 2nd argument of () must be "null" when 1st argument is an…
• Distinct queries cannot be used for pagination. Use GroupBy…
• The value used as a document id or relation key cannot…
• Too few arguments to function
• First argument of must be a field path as "string". Got

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

Appendix: source

Thrown at src/Query/Builder.php:734

        foreach ($toUnset as $column) {
            unset($orders[$column]);
        }

        return $orders;
    }

    /** @inheritdoc */
    #[Override]
    public function whereBetween($column, iterable $values, $boolean = 'and', $not = false)
    {
        $type = 'between';

        if ($values instanceof Collection) {
            $values = $values->all();
        }

        if (is_array($values) && (! array_is_list($values) || count($values) !== 2)) {
            throw new InvalidArgumentException('Between $values must be a list with exactly two elements: [min, max]');
        }

        $this->wheres[] = [
            'column'  => $column,
            'type'    => $type,
            'boolean' => $boolean,
            'values'  => $values,
            'not'     => $not,
        ];

        return $this;
    }

    /** @inheritdoc */
    #[Override]
    public function insert(array $values)
    {
        // Allow empty insert batch for consistency with Eloquent SQL

View on GitHub (pinned to 0634653039)