Context
Session consistency in Cosmos DB can preserve a user's ability to read their own writes. The SDK tracks session information within a client instance. In a web farm, the next request may reach a different process with another client and no knowledge of the previous write. A successful write followed by a stale read can therefore be a session-flow problem.
Prerequisites are the account consistency setting, client SDK version, application routing design and a reproducible item with its partition key. Capture sanitized request correlation and instance identifiers. Keep session tokens out of ordinary application logs unless a controlled diagnostic process specifically protects them.
1. Reproduce across two application instances
Write a uniquely identified test item through instance A and record the returned status, item identity and partition key. Read it through that same instance, then through instance B. Compare behavior without assuming the load balancer maintains affinity. Recreating CosmosClient for every request also discards its accumulated session state.
Confirm that the read uses the correct partition key and does not serve an application cache. A not-found result caused by a wrong key is unrelated to consistency. Record the region and consistency requested by the operation so a client override is not overlooked.
2. Trace the session boundary
Inspect how the write response's session token can reach a later request when a shared session guarantee is required. Microsoft documents propagating the token between web tiers through an appropriate application mechanism. The SDK can then apply it to the subsequent read request.
Tokens are partition-bound. Use the token relevant to the item's partition and preserve it unchanged. Do not interpret the token as a historical snapshot selector or edit its contents. Choose a trusted transport and bind session information to the appropriate user or workflow. Unrelated requests should not inherit another tenant's application context.
3. Implement the smallest required guarantee
Prefer long-lived supported client instances so ordinary SDK session tracking works as intended. Add explicit token flow only where requests crossing processes need the same session. Keep the logic near the write-and-read workflow rather than scattering custom consistency behavior across every repository method.
Evaluate alternative consistency choices against latency, availability and workload requirements before changing the account. Stronger consistency is an architecture decision, not a substitute for checking the wrong partition or a stale HTTP cache. Test session propagation under process restart and regional routing changes.
Diagnostic checkpoints
| Observation | Possible boundary | Next check |
|---|---|---|
| Same instance works, second is stale | Session not shared | Token propagation |
| Every read returns not found | Item or partition mismatch | Exact key and ID |
| Database fresh, response stale | Application cache | Cache key and invalidation |
| Restart changes behavior | Client session lifetime | CosmosClient construction |
Illustrative scenario
A hypothetical checkout service writes a shipping preference through one web instance. Its confirmation page lands on another and briefly shows the old value. The investigation follows the write token and application cache rather than assuming the write failed. This is a fictional example without a claimed consistency incident at a customer.
Verification and session SOP
Verify the workflow while deliberately alternating instances after each write. Include multiple partition keys and separate users. Acceptance requires the intended read-your-writes behavior without mixing contexts, plus correct behavior when no previous write session exists.
Document client lifetime, routing assumptions and token ownership in the application SOP. Monitor stale-read reports with instance and item correlation rather than sensitive values. Revisit the design when introducing a second region, replacing load balancing or moving write and read handlers into different services.
Explore Clouvenix cloud architecture for implementation and operational handover.