mongodb/laravel-mongodb · error · BadMethodCallException

This method is not supported by MongoDB. Use vectorSearch()…

Error message

This method is not supported by MongoDB. Use vectorSearch() with the $filter parameter instead.

What it means

whereVectorDistanceLessThan is a Laravel >= 13.0 vector method combining a vector search with a max-distance filter; MongoDB's builder throws BadMethodCallException because Atlas Vector Search expresses such constraints via the $filter parameter of vectorSearch(), not as where clauses.

Solutions

Use vectorSearch() and pass distance/prefilter constraints through its $filter parameter
Express the constraint with a supported pre-filter (e.g. a range filter on a stored field) in the $filter argument
Catch BadMethodCallException and rewrite the query with vectorSearch($filter: ...)

Example fix

// before
Doc::whereVectorDistanceLessThan('embedding', $vec, 0.5)->get();
// after
Doc::vectorSearch('embedding', $vec, ['filter' => ['field' => 'category', 'in' => $cats]])->get();

Defensive patterns

Strategy: try-catch

Validate before calling

if ($query instanceof MongoDB\Query\Builder) { $query->vectorSearch($col, $vec, ['filter' => $filter])->get(); } else { $query->whereVectorDistanceLessThan($col, $vec, $maxDistance)->get(); }

Try / catch

try { $q->whereVectorDistanceLessThan($col, $vec, $d); } catch (\BadMethodCallException $e) { $q->vectorSearch($col, $vec, ['filter' => $d]); }

Prevention

Express distance constraints as vectorSearch $filter options
Do not mix portable vector where-clauses with MongoDB connections
Pin and review the library's UPGRADING notes when bumping Laravel

When it happens

Trigger: Calling ->whereVectorDistanceLessThan($column, $vector, $maxDistance) on a MongoDB query builder.

Common situations: Porting SQL/pgvector distance filters; mixing Laravel's portable vector API with a MongoDB connection after a framework upgrade.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/Query/Builder.php:2031

     * Base method from Laravel >= 13.0
     * ToDo: mark as `#[Override]` when we drop support for Laravel < 13.0
     *
     * @internal This method is not supported by MongoDB. Use vectorSearch() instead.
     */
    public function whereVectorSimilarTo($column, $vector, $minSimilarity = 0.6, $order = true)
    {
        throw new BadMethodCallException('This method is not supported by MongoDB. Use vectorSearch() instead.');
    }

    /**
     * Base method from Laravel >= 13.0
     * ToDo: mark as `#[Override]` when we drop support for Laravel < 13.0
     *
     * @internal This method is not supported by MongoDB. Use vectorSearch() with the $filter parameter instead.
     */
    public function whereVectorDistanceLessThan($column, $vector, $maxDistance, $boolean = 'and')
    {
        throw new BadMethodCallException('This method is not supported by MongoDB. Use vectorSearch() with the $filter parameter instead.');
    }

    /**
     * Base method from Laravel >= 13.0
     * ToDo: mark as `#[Override]` when we drop support for Laravel < 13.0
     *
     * @internal This method is not supported by MongoDB. Use vectorSearch() with the $filter parameter instead.
     */
    public function orWhereVectorDistanceLessThan($column, $vector, $maxDistance)
    {
        throw new BadMethodCallException('This method is not supported by MongoDB. Use vectorSearch() with the $filter parameter instead.');
    }

    /**
     * Base method from Laravel >= 13.0
     * ToDo: mark as `#[Override]` when we drop support for Laravel < 13.0
     *
     * @internal This method is not supported by MongoDB. Use vectorSearch() instead, which returns vectorSearchScore in the result.

View on GitHub (pinned to 0634653039)