{"record":{"id":"148d22fb98b6bbbe","repo":"mongodb/laravel-mongodb","slug":"invalid-search-index-definition-for-collection-s-the","errorCode":null,"errorMessage":"Invalid search index definition for collection \"%s\", the \"mappings\" key is required. Find documentation at https://www.mongodb.com/docs/manual/reference/command/createSearchIndexes/#search-index-definition-syntax","messagePattern":"Invalid search index definition for collection \"(.+?)\", the \"mappings\" key is required\\. Find documentation at https://www\\.mongodb\\.com/docs/manual/reference/command/createSearchIndexes/#search-index-definition-syntax","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Scout/ScoutEngine.php","lineNumber":454,"sourceCode":"    /**\n     * Create the MongoDB Atlas Search index.\n     *\n     * Accepted options:\n     *  - wait: bool, default true. Wait for the index to be created.\n     *\n     * @see Engine::createIndex()\n     *\n     * @param string            $name    Collection name\n     * @param array{wait?:bool} $options\n     */\n    #[Override]\n    public function createIndex($name, array $options = []): void\n    {\n        assert(is_string($name), new TypeError(sprintf('Argument #1 ($name) must be of type string, %s given', get_debug_type($name))));\n\n        $definition = $this->indexDefinitions[$name] ?? self::DEFAULT_DEFINITION;\n        if (! isset($definition['mappings'])) {\n            throw new InvalidArgumentException(sprintf('Invalid search index definition for collection \"%s\", the \"mappings\" key is required. Find documentation at https://www.mongodb.com/docs/manual/reference/command/createSearchIndexes/#search-index-definition-syntax', $name));\n        }\n\n        // Ensure the collection exists before creating the search index\n        $this->database->createCollection($name);\n\n        $collection = $this->database->selectCollection($name);\n        $collection->createSearchIndex($definition, ['name' => self::INDEX_NAME]);\n\n        if ($options['wait'] ?? true) {\n            $this->wait(function () use ($collection) {\n                $indexes = $collection->listSearchIndexes([\n                    'name' => self::INDEX_NAME,\n                    'typeMap' => ['root' => 'bson'],\n                ]);\n\n                return $indexes->current() && $indexes->current()->status === 'READY';\n            });\n        }","sourceCodeStart":436,"sourceCodeEnd":472,"githubUrl":"https://github.com/mongodb/laravel-mongodb/blob/0634653039468ceb0268a69192bdac64469ed043/src/Scout/ScoutEngine.php#L436-L472","documentation":"createIndex() looks up the index definition from indexDefinitions (falling back to a default) and requires the 'mappings' key that Atlas Search mandates. A definition without 'mappings' is invalid for the createSearchIndexes command, so an InvalidArgumentException with a documentation link is thrown.","triggerScenarios":"Calling ScoutEngine::createIndex($name) when scout.search-indexes (indexDefinitions config) contains a definition for $name lacking the 'mappings' key.","commonSituations":"Typos like 'mapping' instead of 'mappings'; partially migrated Atlas index definitions copied from older configs; empty definitions arrays.","solutions":["Add a 'mappings' key (with 'dynamic' or 'fields') to the index definition for that index name","Fix the spelling of 'mappings' in the Scout search-index configuration","Remove the custom definition to fall back to DEFAULT_DEFINITION if a default index is acceptable","Follow the linked createSearchIndexes definition syntax docs"],"exampleFix":"// before\n'indexes' => ['default' => ['synonyms' => []]],\n// after\n'indexes' => ['default' => ['mappings' => ['dynamic' => true]]],","handlingStrategy":"validation","validationCode":"foreach (config('scout.search-indexes', []) as $name => $def) {\n    if (!isset($def['mappings'])) {\n        throw new InvalidArgumentException(\"Search index '$name' is missing the required 'mappings' key.\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    $engine->createIndex('default');\n} catch (\\InvalidArgumentException $e) {\n    config(['scout.search-indexes.default.mappings' => ['dynamic' => true]]);\n    $engine->createIndex('default');\n}","preventionTips":["Validate scout index definitions in a config smoke test at boot","Copy definitions from the documented createSearchIndexes syntax","Watch for 'mapping' vs 'mappings' typos in review"],"tags":["php","laravel-scout","atlas-search","index-configuration"],"backgroundTag":"missing-required-config-field","analyzedSha":"0634653039468ceb0268a69192bdac64469ed043","analyzedAt":"2026-09-15T02:56:37.067Z","contentChangedAt":"2026-09-15T02:56:37.067Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}