mongodb/laravel-mongodb · error · BadMethodCallException

The "query" and "model" parameters of vectorSearch()…

Error message

The "query" and "model" parameters of vectorSearch() require mongodb/mongodb 2.4+.

What it means

vectorSearch() supports the newer $vectorSearch 'query'/'model' auto-embedding parameters only when the underlying mongodb/mongodb PHP driver library is version 2.4 or newer. Calling with those named parameters against an older library throws BadMethodCallException before any query runs.

Solutions

1. Run composer update mongodb/mongodb to get >= 2.4 (verify with composer show mongodb/mongodb).
2. Require the version explicitly: composer require mongodb/mongodb:^2.4.
3. Until upgraded, omit query/model and pass an explicit 'queryVector' float array so the call works on older drivers.
4. Check self::vectorSearchSupportsAutoEmbedding() (or version_compare on InstalledVersions) before using the parameters.

Example fix

// before
$docs = $builder->vectorSearch(index: 'vsi', path: 'embedding', query: 'find similar', model: 'voyage-3', limit: 5);
// after
$docs = $builder->vectorSearch(index: 'vsi', path: 'embedding', queryVector: $embedding, limit: 5);

$supports = \Composer\InstalledVersions::satisfies(
    new \Composer\Semver\VersionParser(), 'mongodb/mongodb', '>=2.4'
);
if (!$supports) {
    throw new \RuntimeException('Upgrade mongodb/mongodb to >=2.4 for query/model vector search');
}

When it happens

Trigger: composer.lock pins mongodb/mongodb < 2.4 while code calls ->vectorSearch(index: '...', query: 'find similar docs', model: 'voyage-3'); library upgraded laravel-mongodb but driver library lagging; feature-flagged code paths using auto-embedding in mixed-version environments.

Common situations: Missing composer update after adopting vector search with embeddings; partial dependency upgrades in monorepos; documenting/deploying code written against newer driver API.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• Between $values must be a list with exactly two elements…
• 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

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

Appendix: source

Thrown at src/Query/Builder.php:1804

     * NOTE: $vectorSearch is only available for MongoDB Atlas clusters, and is not available for self-managed deployments.
     *
     * @see https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/
     *
     * @return Collection<object|array>
     */
    public function vectorSearch(
        string $index,
        string $path,
        array|null $queryVector = null,
        int $limit = 10,
        bool $exact = false,
        QueryInterface|array|null $filter = null,
        int|null $numCandidates = null,
        string|null $query = null,
        string|null $model = null,
    ): Collection {
        if (($query !== null || $model !== null) && ! self::vectorSearchSupportsAutoEmbedding()) {
            throw new BadMethodCallException('The "query" and "model" parameters of vectorSearch() require mongodb/mongodb 2.4+.');
        }

        // Forward named arguments to the vectorSearch stage, skip null values
        $args = array_filter([
            'index' => $index,
            'limit' => $limit,
            'path' => $path,
            'model' => $model,
            'exact' => $exact,
            'filter' => $filter,
            'numCandidates' => $numCandidates,
            'queryVector' => $queryVector,
            'query' => $query,
        ], fn ($arg) => $arg !== null);

        return $this->aggregate()
            ->vectorSearch(...$args)
            ->addFields(vectorSearchScore: ['$meta' => 'vectorSearchScore'])

View on GitHub (pinned to 0634653039)