Diagnostics: Fixes null contacted region name for multimaster hub fallback (410/21005) by NaluTripician · Pull Request #5618 · Azure/azure-cosmos-dotnet-v3

NaluTripician · 2026-02-18T02:01:13Z

Summary

Fixes issue #5095 where GetContactedRegions() can return (null, <global-endpoint-uri>) for multimaster reads when requests fall back to the account default endpoint after 410/21005 retries with ExcludeRegions.

What this change does

Updates LocationCache.GetLocation(Uri endpoint) to resolve the default/global endpoint to the first available write location name for multimaster as well as single-master.
Updates LocationCache.TryGetLocationForGatewayDiagnostics(Uri endpoint, out string regionName) so that for default-endpoint hostnames in multimaster accounts, diagnostics resolve to hub/write region instead of returning null.
Adds regression coverage in LocationCacheTests for multimaster default-endpoint diagnostics mapping.

Root cause

For multimaster accounts:

GetApplicableEndpoints(...) can fall back to defaultEndpoint when preferred/applicable regional endpoints are exhausted or excluded.
Existing diagnostics resolution in TryGetLocationForGatewayDiagnostics treated endpoints with host matching defaultEndpoint as non-regional and returned regionName = null.
GetLocation(defaultEndpoint) also returned null in multimaster scenarios due to a guard condition.

This caused diagnostics to record contacted regions with an empty/null region name despite correct endpoint routing.

Repro and verification

Repro test added

ValidateTryGetLocationForGatewayDiagnosticsOnDefaultEndpointForMultiMaster
- File: Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/LocationCacheTests.cs
- Validates that in multimaster mode:
  - GetLocation(DefaultEndpoint) returns the hub/write region name.
  - TryGetLocationForGatewayDiagnostics(DefaultEndpoint, out regionName) returns true and non-null hub region.
  - Same behavior for default endpoint with path (new Uri(DefaultEndpoint, "random/path")).

Red/green proof

Without fix (temporarily reverted locally):
- Command: dotnet test .\\Microsoft.Azure.Cosmos\\tests\\Microsoft.Azure.Cosmos.Tests\\Microsoft.Azure.Cosmos.Tests.csproj --filter "FullyQualifiedName~ValidateTryGetLocationForGatewayDiagnosticsOnDefaultEndpointForMultiMaster" --nologo
- Result: Failed with Expected:<location1>. Actual:<(null)>.
With fix restored:
- Same command
- Result: Passed.

Files changed

Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs
Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/LocationCacheTests.cs

Notes

Single-master behavior for default endpoint diagnostics remains unchanged (false + null region name) in existing test coverage.
Change is focused to diagnostics-region resolution behavior and corresponding regression test coverage.

github-actions

All good!

…egions-hub-fallback

Copilot

Pull request overview

Fixes diagnostics region-name resolution when gateway requests in multi-master accounts fall back to the account’s global/default endpoint after 410/21005 retries with excluded regions, preventing (null, <global-endpoint>) entries in GetContactedRegions().

Changes:

Update LocationCache.GetLocation(Uri) to map the default/global endpoint to a write location name for multi-master accounts as well.
Update LocationCache.TryGetLocationForGatewayDiagnostics(Uri, out string) to return the hub/write region for default-endpoint hostnames in multi-master scenarios, and to return false when no region can be resolved.
Add a regression test validating default-endpoint diagnostics mapping in multi-master mode.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs	Adjusts default-endpoint → region-name resolution used by gateway diagnostics.
Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/LocationCacheTests.cs	Adds coverage for multi-master default-endpoint diagnostics mapping; normalizes formatting in touched hunks.

Comments suppressed due to low confidence (1)

Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs:180

GetLocation selects the “first available write location” via AvailableWriteEndpointByLocation.First(). Enumeration order of Dictionary/ReadOnlyDictionary is not guaranteed by contract, so this can produce non-deterministic region names across runtimes. Prefer using the ordered list already maintained in locationInfo.AvailableWriteLocations (e.g., index 0) to pick the hub/first write location deterministically.

            string location = this.locationInfo.AvailableWriteEndpointByLocation.FirstOrDefault(uri => uri.Value == endpoint).Key ?? this.locationInfo.AvailableReadEndpointByLocation.FirstOrDefault(uri => uri.Value == endpoint).Key;

            if (location == null && endpoint == this.defaultEndpoint)
            {
                if (this.locationInfo.AvailableWriteEndpointByLocation.Any())
                {
                    return this.locationInfo.AvailableWriteEndpointByLocation.First().Key;
                }

…egions-hub-fallback

Copilot · 2026-02-25T20:10:19Z

@NaluTripician I've opened a new pull request, #5640, to work on those changes. Once the pull request is ready, I'll request review from you.

…egions-hub-fallback

azure-pipelines · 2026-04-08T18:02:25Z

Azure Pipelines: Successfully started running 1 pipeline(s).

NaluTripician

Review Summary

The core fix is correct — removing the guard that prevented multimaster accounts from resolving the default endpoint to a write region name, and adding a null-safety check on the return path. A couple of concerns below.

Whitespace noise: ~200 lines of trailing-whitespace-only changes obscure the ~15 lines of real logic. Consider a separate formatting commit or .editorconfig enforcement to keep semantic diffs clean.

Test coverage gap: The new test covers useMultipleWriteLocations: true but not the asymmetric case (account is multi-master, client didn't opt in). PR #5640 addresses this — recommend folding it in before merge.

…solution - Use enableMultipleWriteLocations (server-side setting) instead of CanUseMultipleWriteLocations() (client opt-in AND server) so diagnostics resolve the hub region even when the client has UseMultipleWriteLocations disabled. - Use AvailableWriteLocations[0] (ordered ReadOnlyCollection) instead of AvailableWriteEndpointByLocation.First().Key (unordered Dictionary) for deterministic region name selection. - Add test for asymmetric case: account multi-master, client opt-out. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-04-08T18:38:08Z

Azure Pipelines: Successfully started running 1 pipeline(s).

…ter diagnostics - Adds inline comment explaining why enableMultipleWriteLocations (account-level) is used instead of CanUseMultipleWriteLocations() (requires client opt-in) in TryGetLocationForGatewayDiagnostics, since diagnostics should resolve the hub region regardless of client multi-write configuration. - Adds test for unknown/unresolvable non-default endpoint (validates the return regionName != null fix returns false for unknown endpoints). - Adds test for pre-OnDatabaseAccountRead state (validates correct behavior when AvailableWriteLocations is empty and enableMultipleWriteLocations defaults to false). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-04-09T22:29:25Z

Azure Pipelines: Successfully started running 1 pipeline(s).

- Use .Any() instead of .Count > 0 for AvailableWriteLocations guard (per Kiran) - Collapse inner enableMultipleWriteLocations check into ternary (per Kiran) - Reset files to master baseline to eliminate all CRLF/whitespace-only diffs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-04-15T19:12:08Z

Azure Pipelines: Successfully started running 1 pipeline(s).

…egions-hub-fallback

azure-pipelines · 2026-04-16T17:22:40Z

Azure Pipelines: Successfully started running 1 pipeline(s).

- Collapse nested if in GetLocation into single condition - Revert defensive 'return regionName != null' to original 'return true' for non-default endpoint path (unrelated to fix) - Replace 'hub' terminology with 'first available write region' in comments and test variables (MM first write region is not necessarily the hub) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-04-16T17:31:14Z

Azure Pipelines: Successfully started running 1 pipeline(s).

…egions-hub-fallback

azure-pipelines · 2026-04-21T17:20:31Z

Azure Pipelines: Successfully started running 1 pipeline(s).

…egions-hub-fallback

azure-pipelines · 2026-04-21T21:28:07Z

Azure Pipelines: Successfully started running 1 pipeline(s).

…dpoints The fallthrough path returned 'true' unconditionally after calling GetLocation, even when GetLocation returned null for unrecognized endpoints. Changed to 'return regionName != null' to match the contract and the default-endpoint branch. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-04-21T22:51:06Z

Azure Pipelines: Successfully started running 1 pipeline(s).

…egions-hub-fallback

azure-pipelines · 2026-04-23T17:42:56Z

Azure Pipelines: Successfully started running 1 pipeline(s).

…egions-hub-fallback

azure-pipelines · 2026-04-28T18:16:51Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Addresses kushagraThapar review feedback on PR #5618: the existing summary on GetLocation was stale after removing the !CanUseMultipleWriteLocations() guard. Updated doc to: (1) cover the broader write+read regional endpoint case, (2) note that the default-endpoint fallback now applies to both single-master and multi-master, and (3) clarify that the returned write location is just the first in the list, not necessarily the hub region (per his line-179 note). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-04-29T18:11:00Z

Azure Pipelines: Successfully started running 1 pipeline(s).

…egions-hub-fallback

azure-pipelines · 2026-04-30T17:55:16Z

Azure Pipelines: Successfully started running 1 pipeline(s).

…ions-hub-fallback

azure-pipelines · 2026-04-30T19:43:18Z

Azure Pipelines: Successfully started running 1 pipeline(s).

kushagraThapar

LGTM, thanks @NaluTripician

Fix null contacted region name on multimaster default endpoint fallback

010de6c

NaluTripician requested review from FabianMeiswinkel, Pilchie, adityasa, khdang, kirankumarkolli, kirillg, neildsh and sboshra as code owners February 18, 2026 02:01

github-actions Bot reviewed Feb 18, 2026

View reviewed changes

NaluTripician changed the title ~~Fix null contacted region name for multimaster hub fallback (410/21005)~~ Diagnostics: Fixes null contacted region name for multimaster hub fallback (410/21005) Feb 18, 2026

NaluTripician marked this pull request as draft February 18, 2026 02:24

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

0398d02

…egions-hub-fallback

NaluTripician self-assigned this Feb 23, 2026

NaluTripician requested a review from Copilot February 24, 2026 22:33

Copilot started reviewing on behalf of NaluTripician February 24, 2026 22:34 View session

Copilot AI reviewed Feb 24, 2026

View reviewed changes

Comment thread Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs Outdated

NaluTripician added 2 commits February 24, 2026 15:17

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

ae0ff9e

…egions-hub-fallback

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

5c07966

…egions-hub-fallback

Copilot AI mentioned this pull request Feb 25, 2026

Fix TryGetLocationForGatewayDiagnostics to use server-side multi-master setting #5640

Draft

NaluTripician added 2 commits April 7, 2026 15:14

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

1423cde

…egions-hub-fallback

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

04a90a3

…egions-hub-fallback

NaluTripician commented Apr 8, 2026

View reviewed changes

Comment thread Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs Outdated

Comment thread Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs Outdated

Comment thread Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs

NaluTripician marked this pull request as ready for review April 9, 2026 22:29

kirankumarkolli reviewed Apr 15, 2026

View reviewed changes

Comment thread Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs

kirankumarkolli reviewed Apr 15, 2026

View reviewed changes

Comment thread Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

008f9a0

…egions-hub-fallback

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

c724082

…egions-hub-fallback

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

b2ea3f0

…egions-hub-fallback

NaluTripician requested a review from kushagraThapar as a code owner April 21, 2026 21:27

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

dbf081c

…egions-hub-fallback

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

15666a2

…egions-hub-fallback

kushagraThapar reviewed Apr 28, 2026

View reviewed changes

Comment thread Microsoft.Azure.Cosmos/src/Routing/LocationCache.cs Outdated

Merge branch 'master' into users/nalutripician/issue-5095-contacted-r…

8787eb0

…egions-hub-fallback

NaluTripician requested review from jeet1995, kundadebdatta and xinlian12 as code owners April 30, 2026 17:54

Merge branch 'main' into users/nalutripician/issue-5095-contacted-reg…

340e0f2

…ions-hub-fallback

kushagraThapar approved these changes May 1, 2026

View reviewed changes

Conversation

NaluTripician commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What this change does

Root cause

Repro and verification

Repro test added

Red/green proof

Files changed

Notes

Uh oh!

github-actions Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI commented Feb 25, 2026

Uh oh!

azure-pipelines Bot commented Apr 8, 2026

Uh oh!

NaluTripician left a comment

Choose a reason for hiding this comment

Review Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

azure-pipelines Bot commented Apr 8, 2026

Uh oh!

azure-pipelines Bot commented Apr 9, 2026

Uh oh!

azure-pipelines Bot commented Apr 15, 2026

Uh oh!

Uh oh!

Uh oh!

azure-pipelines Bot commented Apr 16, 2026

Uh oh!

azure-pipelines Bot commented Apr 16, 2026

Uh oh!

azure-pipelines Bot commented Apr 21, 2026

Uh oh!

azure-pipelines Bot commented Apr 21, 2026

Uh oh!

azure-pipelines Bot commented Apr 21, 2026

Uh oh!

azure-pipelines Bot commented Apr 23, 2026

Uh oh!

azure-pipelines Bot commented Apr 28, 2026

Uh oh!

Uh oh!

azure-pipelines Bot commented Apr 29, 2026

Uh oh!

azure-pipelines Bot commented Apr 30, 2026

Uh oh!

azure-pipelines Bot commented Apr 30, 2026

Uh oh!

kushagraThapar left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

NaluTripician commented Feb 18, 2026 •

edited

Loading

github-actions Bot left a comment •

edited

Loading