azcosmos: cold partition range cache refresh rejects duplicate range revisions

[Tonkpils]

Bug Report

• Import path: github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
• SDK version: v1.5.0
• Go version: go1.26.3

What happened?

A new Cosmos client can intermittently fail its first ReadFeedRanges or ReadChangeFeed call against a container undergoing physical partition splits.

The partition-range change feed can return multiple revisions of the same range ID with different boundaries. The SDK then rejects the routing map because the range appears to overlap itself:

partition key range cache refresh failed: service returned an incomplete set
of ranges (... issue: overlap between range id=X (...) and range id=X (...))

The affected path is:

getPartitionKeyRanges
  -> partitionKeyRangeCache.getRoutingMap
  -> refreshEntryDetached
  -> fetchAllChangeFeedPages
  -> newCollectionRoutingMap
  -> isCompleteSetOfRanges

newCollectionRoutingMap appends every surviving record to orderedRanges. It separately creates rangeByID, which deduplicates by ID, but does not rebuild orderedRanges from that map. Validation therefore runs against the non-deduplicated slice.

• Full routing-map construction
• Incremental merge deduplicates by range ID

What did you expect or want to happen?

The full-refresh path should produce one current entry per physical range ID before validating continuity, matching the incremental merge behavior.

Alternatively, this condition should be retried internally or returned as a typed retryable error.

How can we reproduce it?

1. Create a new azcosmos.Client against a partitioned container undergoing physical partition splits.
2. Call ReadFeedRanges, or start concurrent ReadChangeFeed calls, while the client’s partition-range cache is empty.
3. Have the full partition-range change feed return multiple revisions of one range ID.
4. Observe newCollectionRoutingMap retain both revisions in orderedRanges.
5. Observe isCompleteSetOfRanges report that the range overlaps itself.

Concurrent callers receive the same error because they share the in-flight cache refresh. A later refresh can succeed and populate the cache.

Anything we should know about your environment?

The issue occurs during cold cache initialization. Long-lived clients can recover when a later operation successfully refreshes the cache, while short-lived jobs can fail on each new client initialization.

[github-actions]

Thank you for your feedback. Tagging and routing to the team member(s) best able to assist.

//cc: @MehaKaushik @Pilchie @wmengmsft

[github-actions]

🎯 Agentic Issue Triage

Summary: The azcosmos SDK's full partition-range cache refresh intermittently fails when a container is undergoing physical partition splits, because newCollectionRoutingMap retains duplicate range revisions in orderedRanges before running overlap validation.

📋 Issue Details

Module: github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos (v1.5.0)
Affected API: newCollectionRoutingMap / isCompleteSetOfRanges in cosmos_collection_routing_map.go
Scenarios:

• Cold cache initialization against a container undergoing physical partition splits returns multiple revisions of the same range ID
• orderedRanges is not deduplicated before validation, causing a self-overlap error
• Concurrent callers share the in-flight refresh and all receive the same error; long-lived clients can recover on a later refresh but short-lived jobs cannot

Root ask: Deduplicate orderedRanges by range ID before calling isCompleteSetOfRanges (matching the behavior of the incremental merge path), or internally retry / expose this as a typed retryable error.

🔎 Debugging / Reproduction Notes

The incremental merge path (rangeByID map) already deduplicates correctly, but the full-refresh path builds orderedRanges from the raw append and does not rebuild it from the deduplicated map before validation.

Suggested investigation steps:

1. Review newCollectionRoutingMap in cosmos_collection_routing_map.go lines 27–61 to confirm orderedRanges is populated from a non-deduplicated slice.
2. Compare with the incremental merge logic (lines 64–113) where rangeByID is the authoritative deduplicated source.
3. Rebuild orderedRanges from rangeByID after deduplication (or sort and deduplicate the slice in place) before passing it to isCompleteSetOfRanges.
4. Alternatively, add a retry loop around the full-refresh call in getPartitionKeyRanges / refreshEntryDetached to handle this transient condition.

🏷️ Label Confidence

• Category: Client — module path sdk/data/azcosmos is outside sdk/resourcemanager/, so it is a data-plane client library
• Service: Cosmos — directly maps to the sdk/data/azcosmos package and matches the %Cosmos service label used in CODEOWNERS and prior issues
• Confidence: High — the module path, service, and category are all unambiguous; reference issue Possible bug in the Azure cosmos SDK: undefined min function in cosmos_location_cache.go #22868 also uses the Cosmos service label for this package

👥 Owner Routing

• Matched CODEOWNERS entry: # ServiceLabel: %Cosmos (line 45) — matched because the predicted service label Cosmos is present and this is the first %Cosmos entry encountered in a bottom-to-top scan
• AzureSdkOwners: none listed for this entry
• ServiceOwners: @MehaKaushik @Pilchie @Wmengmsft
• Routing action: Added Service Attention and needs-team-attention labels; ServiceOwners mentioned in routing comment above
• Scan notes: Also encountered # ServiceLabel: %Cosmos at line 42 with AzureSdkOwners @jhendrixMSFT and different ServiceOwners, but line 45 was reached first in the bottom-to-top scan and matched, so scanning stopped there

Generated by Agentic Triage for #27246 · 27.3 AIC · ⌖ 9.91 AIC · ⊞ 9.2K · ◷

[Pilchie]

@simorenoh - can you take a look?