From 604ef77e6918e1c2cd65c1be7df26fa02ee9b9fa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= <jerome@tamarelle.net>
Date: Wed, 5 Nov 2025 14:11:18 -0500
Subject: [PATCH] PHPLIB-1689 Make the Atlas Search exception more specific

---
 src/Exception/SearchNotSupportedException.php | 26 +++++++++++++++++++
 src/Operation/Aggregate.php                   | 12 ++++++++-
 2 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100644 src/Exception/SearchNotSupportedException.php

diff --git a/src/Exception/SearchNotSupportedException.php b/src/Exception/SearchNotSupportedException.php
new file mode 100644
index 000000000..3b75e7156
--- /dev/null
+++ b/src/Exception/SearchNotSupportedException.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace MongoDB\Exception;
+
+use MongoDB\Driver\Exception\ServerException;
+use Throwable;
+
+use function in_array;
+
+final class SearchNotSupportedException extends ServerException
+{
+    public static function isSearchNotSupportedError(Throwable $e): bool
+    {
+        if (! $e instanceof ServerException) {
+            return false;
+        }
+
+        return in_array($e->getCode(), [
+            59,      // MongoDB 4 to 6, 7-community: no such command: 'createSearchIndexes'
+            40324,   // MongoDB 4 to 6: Unrecognized pipeline stage name: '$listSearchIndexes'
+            115,     // MongoDB 7-ent: Search index commands are only supported with Atlas.
+            6047401, // MongoDB 7: $listSearchIndexes stage is only allowed on MongoDB Atlas
+            31082,   // MongoDB 8: Using Atlas Search Database Commands and the $listSearchIndexes aggregation stage requires additional configuration.
+        ], true);
+    }
+}
diff --git a/src/Operation/Aggregate.php b/src/Operation/Aggregate.php
index b5da6470c..a4795ba95 100644
--- a/src/Operation/Aggregate.php
+++ b/src/Operation/Aggregate.php
@@ -21,12 +21,14 @@
 use MongoDB\Driver\Command;
 use MongoDB\Driver\CursorInterface;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
+use MongoDB\Driver\Exception\ServerException;
 use MongoDB\Driver\ReadConcern;
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Driver\Server;
 use MongoDB\Driver\Session;
 use MongoDB\Driver\WriteConcern;
 use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Exception\SearchNotSupportedException;
 use MongoDB\Exception\UnexpectedValueException;
 use MongoDB\Exception\UnsupportedException;
 use MongoDB\Model\CodecCursor;
@@ -233,7 +235,15 @@ public function execute(Server $server): CursorInterface
             $this->createCommandOptions(),
         );
 
-        $cursor = $this->executeCommand($server, $command);
+        try {
+            $cursor = $this->executeCommand($server, $command);
+        } catch (ServerException $exception) {
+            if (SearchNotSupportedException::isSearchNotSupportedError($exception)) {
+                throw new SearchNotSupportedException('Search is not supported by the connected server', $exception->getCode(), $exception);
+            }
+
+            throw $exception;
+        }
 
         if (isset($this->options['codec'])) {
             return CodecCursor::fromCursor($cursor, $this->options['codec']);