mongodb/laravel-mongodb · warning · MongoDBRuntimeException

Atlas search index operation time out after

Error message

Atlas search index operation time out after %s seconds

What it means

After issuing createSearchIndexes, the engine polls until the index becomes queryable, sleeping 1s per iteration up to WAIT_TIMEOUT_SEC. If the index is still not ready after the timeout, a MongoDBRuntimeException is thrown reporting the number of seconds waited.

Solutions

1. Retry createIndex() after the Atlas cluster finishes provisioning the index
2. Verify the index status in the Atlas UI (Atlas Search index should reach 'Active')
3. Increase patience/retry around deployment scripts that call createIndex during migrations
4. Check Atlas alerts and cluster health; escalate or recreate the index if it is stuck in a failed state

Example fix

// before
$engine->createIndex('search_index'); // may throw on slow clusters
// after
try {
    $engine->createIndex('search_index');
} catch (\MongoDB\Driver\Exception\RuntimeException $e) {
    sleep(30);
    $engine->createIndex('search_index'); // retry after Atlas provisioning
}

// Pre-check cluster reachability before createIndex
$engine->getIndexClient()->listSearchIndexes(); // throws early on connectivity problems

$retries = 3;
while (true) {
    try { $engine->createIndex('search_index'); break; }
    catch (\MongoDB\Driver\Exception\RuntimeException $e) {
        if (str_contains($e->getMessage(), 'time out after') && --$retries > 0) { sleep(30); continue; }
        throw $e;
    }
}

When it happens

Trigger: Calling createIndex() on a slow Atlas cluster where the search index stays in a non-buildable/pending state beyond WAIT_TIMEOUT_SEC (index build stuck, large initial sync, Atlas maintenance, network latency).

Common situations: Free/shared Atlas tiers with slow index provisioning; transient Atlas control-plane issues; very large collections during first-time index builds.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Cannot sort by a field named 'score' together with Atlas…
• Cannot sort by '_score' in ascending order; Atlas Search…
• Invalid search index definition for collection
• The MongoDB Scout collection
• Between $values must be a list with exactly two elements…

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

Appendix: source

Thrown at src/Scout/ScoutEngine.php:565

    }

    /**
     * Wait for the callback to return true, use it for asynchronous
     * Atlas Search index management operations.
     */
    private function wait(Closure $callback): void
    {
        // Fallback to time() if hrtime() is not supported
        $timeout = (hrtime()[0] ?? time()) + self::WAIT_TIMEOUT_SEC;
        while ((hrtime()[0] ?? time()) < $timeout) {
            if ($callback()) {
                return;
            }

            sleep(1);
        }

        throw new MongoDBRuntimeException(sprintf('Atlas search index operation time out after %s seconds', self::WAIT_TIMEOUT_SEC));
    }
}

View on GitHub (pinned to 0634653039)