Repository navigation
Description
Observed Behavior
AzureDocumentDBStore and AzureDocumentDBCollection reject connection strings, client options, and .env options when a PyMongo async client, database, or collection is injected. An injected account-level client also requires database_name explicitly instead of allowing the remaining selector to fall back to AZURE_DOCUMENTDB_DATABASE_NAME.
Affected file: python/packages/azure-documentdb/agent_framework_azure_documentdb/_vector_store.py.
Expected Behavior
The most specific injected SDK object should take precedence over all client-construction inputs. Connection strings, client options, and environment connection settings should not be read or validated when a suitable client/database/collection is present. Any unresolved database or collection selector should then use explicit argument > environment > focused error.
Injected clients remain caller-owned.
Steps to Reproduce
- Create a caller-owned
AsyncMongoClient. - Pass it to
AzureDocumentDBStorewithdatabase_nameand a connection or.envoption. - Observe the conflict error before the injected client is used.
Minimal Reproduction
from unittest.mock import MagicMock
from pymongo.asynchronous.mongo_client import AsyncMongoClient
from agent_framework_azure_documentdb import AzureDocumentDBStore
client = MagicMock(spec=AsyncMongoClient)
AzureDocumentDBStore(
client=client,
database_name="vectors",
connection_string="mongodb://ignored",
)Error Messages and Stack Traces
ValueError: client cannot be combined with connection settings or client_options.
Package Versions
agent-framework-azure-documentdb: 1.0.0a261030; main at 93c346f
Python Version
Python 3.13.1
Operating System
macOS
Regression
Unknown
Additional Context
Compatibility impact: alpha constructors would stop raising for redundant connection settings. Database-name environment fallback could become available for an injected account client. Type and resource-name validation should remain.
Focused acceptance tests:
- Injected collection/database/client paths ignore connection strings, client options, and
.envvalues. - Remaining database and collection selectors use explicit values before environment values.
- Invalid ambient connection settings cannot block an injected object.
- No client factory is called and injected clients remain open.
- No-injection initialization keeps current validation and ownership.
AI assistance: I used an AI coding assistant to audit and reproduce the behavior.
Acknowledgements
- I searched existing issues and did not find a duplicate.
- I personally verified this behavior and the reproduction details are authentic.
Metadata
Metadata
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
he-yufeng commentedon Nov 3, 2026
I’ll take this one. I’ll cover the injected collection, database, and account-client paths, including selector fallback, bypass of ambient connection settings, and caller-owned cleanup, while keeping the no-injection initialization contract unchanged.
eavanvalkenburg commentedon Nov 9, 2026
/plan Use the existing maintainer-defined injection scope and #9999 implementation rather than creating a parallel fix. Establish the compatibility contract across injected collection, database, and account-client paths: bypass client-construction settings while resolving only genuinely missing resource selectors. Preserve explicit selectors and registered model definitions ahead of environment fallback, multiple-injection/type/name-mismatch errors, caller ownership, and unchanged no-injection behavior. Check that invalid ambient connection settings cannot leak into selector-only resolution or redirect a resolved injected resource. Cover the full injection/selector/cleanup matrix and estimate the complete production-code scope before any new readiness or assignment decision. Planning only; this does not authorize a competing implementation.
github-actions commentedon Nov 9, 2026
Summary
Today, passing an injected PyMongo client, database or collection to
AzureDocumentDBStoreorAzureDocumentDBCollectionfails if you also pass a connection string, client options or.envoptions. An injected account client also requiresdatabase_name, and does not fall back toAZURE_DOCUMENTDB_DATABASE_NAME. The expected behavior is that the injected object wins, and only a missing database or collection name is resolved afterwards.I checked this against
mainin_vector_store.py. This is planning only. I did not run anything, and I did not look at #9999's diff. I only note that it is an open PR linked to this issue.What I confirmed
_create_client(around lines 155-210) raises"database cannot be combined..."or"client cannot be combined..."when settings are present with an injected object. For a client it raises"database_name is required with an injected client."before it reaches any environment lookup.AzureDocumentDBCollection.__init__(around lines 624-652) has a third, similar rejection forcollection=. It also checks thatcollection_namematches the injected collection.AzureDocumentDBStore.__init__calls_create_clientdirectly, so one fix there covers the store.load_settings(AzureDocumentDBSettings, ...). It is reached only on the no-injection path.test_settings.pyalready check that injection bypasses settings loading and leaves the client open.test_injected_client_rejects_connection_settingspins the current rejection, so it must change.Recommendation
Code change, plus a small README update. This is a real behavior inconsistency in an alpha package, and it is already labeled
ready-for-implementationand assigned. I recommend that the change land in the existing #9999 work rather than in a second fix. No sample is needed. The workaround today is to omit the redundant settings and always passdatabase_name. That is easy to do, but it is inconsistent with the other settings paths.Compatibility: constructors that used to raise on redundant settings will stop raising. This is acceptable for alpha and is already stated in the issue. Unchanged: wrong-type errors, collection-name mismatch, no-injection validation and ownership.
Proposed plan
The production change is small and confined to the single file
_vector_store.py, plus docs. I estimate about two functions,_create_clientand thecollectionbranch ofAzureDocumentDBCollection.__init__, with no new public API.Precedence contract (most specific wins):
collection>database>client> create from settings. For injected objects, ignoreconnection_string,client_options,env_file_pathandenv_file_encoding. Do not read or validate them, and do not call the client factory.Keep the existing errors:
collection,databaseandclientstill raises. That iscollectionwithdatabaseorclient, anddatabasewithclient. Today those combinations raise, and the plan should state explicitly that they keep raising.TypeError.collection_namethat differs from the injected collection still raises.Selector-only resolution (client path):
database_namefirst, thenAZURE_DOCUMENTDB_DATABASE_NAME(read from the selected.env/environment), then a focused error.AZURE_DOCUMENTDB_CONNECTION_STRINGcould still interfere. Needs a decision: confirm thatload_settingscan load a subset, or read the one value separately.env_file_pathandenv_file_encodingshould apply only to this selector lookup. They should not be rejected.Injected database or collection: these are already resolved, so they need no environment lookup.
database_namethat conflicts with the injected database's name should raise a mismatch error, likecollection_name. The alternative is to keep rejecting it. Either way, ambient environment values must never redirect an injected resource.AzureDocumentDBCollection, thecollection_nameand the registered model definition keep priority over environment fallback. Only an unresolved collection name on a client or database path uses the existing model-definition default.Ownership: injected objects keep
owned=Falseandmanaged_client=False.aclose()and context exit never close them. Store-created child collections stay shared and never close the account client.Docs: update the README wording about bypassing settings and the constructor docstrings that say the client "requires
database_name". I do not expect changes to the changelog or to the public consumer skills.Test matrix (offline, mocks)
Rows are the injected object: none, client, database or collection. Columns are the settings supplied: none, connection string, client options,
.envoptions, or invalid ambient connection string. Cases to cover:.envoptions, and an invalid ambient connection string.AsyncMongoClientis never constructed andload_settingsnever fails because of those values..env/environment, then a clear error. An invalid ambient connection string does not interfere.database_nameorcollection_name: mismatch error (the policy chosen in step 4).aclose()and after context exit, for both the store and the collection, including children created throughstore.get_collection.test_injected_client_rejects_connection_settingswith the new contract.Success means these tests pass with the issue's reproduction constructing without error. I have not run any of this.
Open point
I only need one maintainer answer: should an explicit
database_namethat conflicts with an injected database or collection be an error, or be silently ignored? I recommend an error, because it is consistent with the existingcollection_namecheck.