{"record":{"id":"ad12304da266176a","repo":"microsoft/semantic-kernel","slug":"failed-to-validate-azure-cosmos-db-nosql-settings","errorCode":null,"errorMessage":"Failed to validate Azure Cosmos DB NoSQL settings.","messagePattern":"Failed to validate Azure Cosmos DB NoSQL settings\\.","errorType":"exception","errorClass":"VectorStoreInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/azure_cosmos_db.py","lineNumber":597,"sourceCode":"            cosmos_client (CosmosClient): The custom Azure Cosmos DB NoSQL client whose lifetime is managed by the user.\n                                          Defaults to None.\n            create_database (bool): If True, the database will be created if it does not exist.\n                                    Defaults to False.\n            env_file_path (str): The path to the .env file. Defaults to None.\n            env_file_encoding (str): The encoding of the .env file. Defaults to None.\n            credential: The credential to use for authentication to Azure Cosmos DB NoSQL.\n            kwargs: Additional keyword arguments.\n        \"\"\"\n        try:\n            cosmos_db_nosql_settings = CosmosNoSqlSettings(\n                url=url,\n                key=key,\n                database_name=database_name,\n                env_file_path=env_file_path,\n                env_file_encoding=env_file_encoding,\n            )\n        except ValidationError as e:\n            raise VectorStoreInitializationException(\"Failed to validate Azure Cosmos DB NoSQL settings.\") from e\n\n        if cosmos_db_nosql_settings.database_name is None:\n            raise VectorStoreInitializationException(\"The name of the Azure Cosmos DB NoSQL database is missing.\")\n\n        if cosmos_client is None:\n            if cosmos_db_nosql_settings.key is not None:\n                cosmos_client = CosmosClient(\n                    str(cosmos_db_nosql_settings.url), credential=cosmos_db_nosql_settings.key.get_secret_value()\n                )\n            else:\n                if credential is None:\n                    raise VectorStoreInitializationException(\n                        \"The 'credential' parameter is required for authentication.\"\n                    )\n                cosmos_client = CosmosClient(str(cosmos_db_nosql_settings.url), credential=credential)\n\n        super().__init__(\n            cosmos_client=cosmos_client,","sourceCodeStart":579,"sourceCodeEnd":615,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/azure_cosmos_db.py#L579-L615","documentation":"CosmosNoSqlBase.__init__ constructs CosmosNoSqlSettings from url/key/database_name and env files. If pydantic validation fails (missing/malformed URL, conflicting key + credential, bad env), it raises VectorStoreInitializationException. This guards all NoSQL collection/store construction.","triggerScenarios":"Raised in CosmosNoSqlBase.__init__ when CosmosNoSqlSettings(...) raises ValidationError. Triggered when the Cosmos DB account URL is missing or not a valid HttpUrl, when env_file_path is unreadable, or when a combination of url/key/credential fails settings-level constraints.","commonSituations":"Missing COSMOS_DB_NOSQL_URL environment variable in CI/local dev. URL without https:// scheme. Conflicting key vs credential configuration. Wrong env var alias after an SDK rename.","solutions":["Provide url= explicitly (a valid https URL) or set the corresponding environment variable.","If using a key, also set the key env var; if using Entra ID, pass credential= and omit key.","Pass a pre-built cosmos_client to bypass settings construction.","Check env var names against CosmosNoSqlSettings field aliases."],"exampleFix":"// before\nclient = CosmosNoSqlCollection(record_type=MyModel, collection_name=\"items\")\n// after\nclient = CosmosNoSqlCollection(record_type=MyModel, collection_name=\"items\", url=\"https://myaccount.documents.azure.com:443/\", key=\"<primary-key>\")","handlingStrategy":"try-catch","validationCode":"import os\nrequired = [\"COSMOS_DB_NOSQL_URL\"]  # confirm exact alias in CosmosNoSqlSettings\nmissing = [v for v in required if not os.getenv(v)]\nif missing:\n    raise RuntimeError(f\"Missing env vars: {missing}\")\n","typeGuard":null,"tryCatchPattern":"try:\n    base = CosmosNoSqlBase(...)\nexcept VectorStoreInitializationException as e:\n    if isinstance(e.__cause__, ValidationError):\n        # show field-level errors from e.__cause__.errors()\n        ...\n","preventionTips":["Validate required env vars at app startup.","Pass url/key explicitly in scripts to avoid env coupling.","Use e.__cause__.errors() to surface which field failed."],"tags":["azure-cosmos-db","vector-store","initialization","environment"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}