microsoft/semantic-kernel · error · VectorStoreInitializationException

Failed to create MongoDB Atlas settings.

Error message

Failed to create MongoDB Atlas settings.

What it means

Raised by the MongoDBAtlasCollection constructor (VectorStoreInitializationException, wrapping a pydantic ValidationError) when MongoDBAtlasSettings cannot be built from arguments + environment. MongoDBAtlasSettings requires a connection_string (MONGODB_ATLAS_CONNECTION_STRING) as a SecretStr; database_name and index_name have defaults. A ValidationError here almost always means the connection string is missing or malformed.

Source

Thrown at python/semantic_kernel/connectors/mongodb.py:227

                database_name=database_name or DEFAULT_DB_NAME,
                index_name=index_name or DEFAULT_SEARCH_INDEX_NAME,
                managed_client=managed_client,
                embedding_generator=embedding_generator,
            )
            if callable(mongo_client.append_metadata):
                mongo_client.append_metadata(DRIVER_METADATA)
            return

        try:
            mongodb_atlas_settings = MongoDBAtlasSettings(
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
                connection_string=connection_string,
                database_name=database_name,
                index_name=index_name,
            )
        except ValidationError as exc:
            raise VectorStoreInitializationException("Failed to create MongoDB Atlas settings.") from exc

        mongo_client = AsyncMongoClient(
            mongodb_atlas_settings.connection_string.get_secret_value(),
            driver=DRIVER_METADATA,
        )

        super().__init__(
            record_type=record_type,
            definition=definition,
            collection_name=collection_name,
            mongo_client=mongo_client,
            managed_client=managed_client,
            database_name=mongodb_atlas_settings.database_name,
            index_name=mongodb_atlas_settings.index_name,
            embedding_generator=embedding_generator,
        )

    def _get_database(self) -> AsyncDatabase:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set MONGODB_ATLAS_CONNECTION_STRING in your environment/.env to a valid mongodb+srv:// URI.
2. Pass connection_string= explicitly, or env_file_path= pointing at the right .env.
3. Inspect the wrapped ValidationError (`exc.__cause__`) for the exact missing/invalid field.

Example fix

// before
store = MongoDBAtlasCollection(record_type=Doc, collection_name='docs')  # raises
// after
// set MONGODB_ATLAS_CONNECTION_STRING=mongodb+srv://... in .env
store = MongoDBAtlasCollection(record_type=Doc, collection_name='docs')

import os
conn = os.environ.get('MONGODB_ATLAS_CONNECTION_STRING')
assert conn and conn.startswith('mongodb'), 'set MONGODB_ATLAS_CONNECTION_STRING to a mongodb+srv:// URI'
collection = MongoDBAtlasCollection(record_type=Doc, collection_name='docs')

from semantic_kernel.exceptions import VectorStoreInitializationException
try:
    collection = MongoDBAtlasCollection(record_type=Doc, collection_name='docs')
except VectorStoreInitializationException as e:
    raise SystemExit(f'MongoDB settings invalid: {e.__cause__!r}') from e

When it happens

Trigger: Constructing a MongoDB collection without passing connection_string and without the MONGODB_ATLAS_CONNECTION_STRING env var set; or passing an invalid (non-URI) connection string. Raised only when no external mongo_client was supplied.

Common situations: .env file not loaded or wrong name; env var typo; secret missing in CI/deployment; connection string not a mongodb(+srv):// URI; python-dotenv env_file_path not pointing at the file.

Related errors

• Distance function {field.distance_function} is not supported
• Failed to create Anthropic settings.
• Failed to create Google settings.
• Failed to create Azure OpenAI settings: {exc}
• Please provide an Azure OpenAI endpoint

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/74575feece32c365. Report an issue: GitHub.