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() instead, which returns results ordered by vector score.

What it means

orderByVectorDistance sorts SQL vector-search results by computed distance; MongoDB's Atlas Vector Search already returns results ordered by score, so the builder throws BadMethodCallException telling you to use vectorSearch(), which returns results sorted by vector score natively.

Solutions

Remove the orderBy call — vectorSearch() already returns results ordered by vector score
Use vectorSearch() instead of a manual search + orderByVectorDistance combination
Catch BadMethodCallException and drop the ordering step when using vectorSearch

Example fix

// before
$docs = Doc::orderByVectorDistance('embedding', $vec)->limit(5)->get();
// after
$docs = Doc::vectorSearch('embedding', $vec)->limit(5)->get(); // already score-ordered

Defensive patterns

Strategy: fallback

Validate before calling

if ($builder instanceof MongoDB\Query\Builder) { $results = $builder->vectorSearch($col, $vec)->limit($n)->get(); }

Try / catch

try { $q->orderByVectorDistance($col, $vec); } catch (\BadMethodCallException $e) { /* vectorSearch results are already score-ordered */ }

Prevention

Rely on vectorSearch()'s native score ordering; do not add distance orderBy
Remove explicit distance sorting when migrating from pgvector to MongoDB
Review the library's Atlas Vector Search guide before writing search queries

When it happens

Trigger: Calling ->orderByVectorDistance($column, $vector) on a MongoDB query builder after performing a search.

Common situations: Codebase migrated from pgvector where explicit distance ordering was needed; new Laravel 13 vector APIs called on a MongoDB connection.

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/c1346446b1dd5ef9. Report an issue: GitHub.

Appendix: source

Thrown at src/Query/Builder.php:2064

     * 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.
     */
    public function selectVectorDistance($column, $vector, $as = null)
    {
        throw new BadMethodCallException('This method is not supported by MongoDB. Use vectorSearch() instead, which returns vectorSearchScore in the result.');
    }

    /**
     * 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 results ordered by vector score.
     */
    public function orderByVectorDistance($column, $vector = [])
    {
        throw new BadMethodCallException('This method is not supported by MongoDB. Use vectorSearch() instead, which returns results ordered by vector score.');
    }
}

View on GitHub (pinned to 0634653039)