Owner Resource Not Found (Gateway V2 Connection Mode and Direct Connection Mode): Remaps sub-status to 1003 for requests to child resources against non-existent container. #47604

jeet1995 · 2025-12-26T07:00:51Z

Description

The objective of this PR is to add Owner Resource Not Found (1003) as sub-status code mapping when the owning resource is not found specifically the DocumentCollection resource. The main motivation is disambiguation - is it the child resource not present (such as a document) or its encapsulating resource such as a container. This can help an application developer debug better.

Scenarios tested and fixed

For Direct Mode and Gateway V2 Mode, ensure both container never existed and stale container cache scenarios are appropriately handled.

For Gateway Mode, ensure container never existed scenarios are appropriately handled.

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

…und.

jeet1995 · 2025-12-26T15:03:54Z

/azp run java - cosmos - tests

azure-pipelines · 2025-12-26T15:04:19Z

Azure Pipelines successfully started running 1 pipeline(s).

…und.

…operations.

Copilot

Pull request overview

This PR adds sub-status code 1003 (Owner Resource Not Found) for requests to child resources (e.g., documents) when the owning container doesn't exist. The changes ensure proper error reporting across Direct Mode, Gateway V2 Mode, and Gateway Mode connection types.

Key Changes

Added error mapping logic to set sub-status code 1003 when container resolution fails during child resource operations
Introduced new setSubStatusCode method in CosmosException API via ImplementationBridgeHelpers
Added comprehensive test coverage for container not found scenarios across different connection modes

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
QueryPlanRetriever.java	Added error mapping to set sub-status 1003 for 404 errors during query plan retrieval
RxCollectionCache.java	Added error mapping handlers in collection resolution paths to set sub-status 1003 for child resource operations
StaleResourceRetryPolicy.java	Added enclosingOperationTargetResourceType parameter and error mapping logic for retry scenarios
RxDocumentClientImpl.java	Updated retry policy instantiation with ResourceType.Document parameter for point operations
ImplementationBridgeHelpers.java	Added setSubStatusCode method to CosmosExceptionAccessor interface
CosmosException.java	Implemented setSubStatusCode accessor method
CosmosNotFoundTests.java	New comprehensive test class covering non-existent and deleted container scenarios
FaultInjectionTestBase.java	Enhanced helper methods to support bulk operations and feed range testing
StaleResourceExceptionRetryPolicyTest.java	Updated test constructor calls with new null parameter

sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/CosmosNotFoundTests.java

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/caches/RxCollectionCache.java

sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/CosmosNotFoundTests.java

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/StaleResourceRetryPolicy.java

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/caches/RxCollectionCache.java

…into AzCosmos_RemapSubStatusForDocRequestsAgainstNonExistentContainer

jeet1995 · 2025-12-29T15:38:11Z

/azp run java - cosmos - tests

azure-pipelines · 2025-12-29T15:38:37Z

Azure Pipelines successfully started running 1 pipeline(s).

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/StaleResourceRetryPolicy.java

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/caches/RxCollectionCache.java

jeet1995 · 2025-12-30T16:28:30Z

/azp run java - cosmos - tests

azure-pipelines · 2025-12-30T16:28:58Z

Azure Pipelines successfully started running 1 pipeline(s).

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/caches/RxCollectionCache.java

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java

xinlian12 · 2025-12-30T23:19:14Z

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/StaleResourceRetryPolicy.java

                AtomicReference<String> oldCollectionRid = new AtomicReference<>();
                return this.clientCollectionCache
-                    .resolveByNameAsync(this.getMetadataDiagnosticsContext(), collectionLink, requestOptionProperties)
+                    .resolveByNameAsync(this.getMetadataDiagnosticsContext(), collectionLink, requestOptionProperties, null, this.request, this.enclosingOperationTargetResourceType)


when would this.request.getOperationType != this.enclosingOperationTargetResourceType?

Above is not expected to be unequal. This is primarily for defense in depth. The request entity is set once StaleResourceRetryPolicy is already instantiated whereas enclosingOperationTargetResourceType is set through the constructor (more guarantees to be initialized).

xinlian12 · 2025-12-30T23:19:56Z

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/query/QueryPlanRetriever.java

+
+                    CosmosException cosmosException = Utils.as(throwable, CosmosException.class);
+
+                    if (HttpConstants.StatusCodes.NOTFOUND == (cosmosException.getStatusCode())) {


sam question -> would this still be needed?

Yes, I'd think - the QueryPlan call goes through RxGatewayStoreModel and gets a 404/0 back when the corresponding collection doesn't exist. This is slightly different for other Document calls whose call path peek into RxCollectionCache first. So remapping is done in QueryPlanRetriever (wanted to keep the transport layer devoid of business logic).

xinlian12

LGTM, thanks

jeet1995 · 2026-01-02T15:08:20Z

/azp run java - cosmos - tests

azure-pipelines · 2026-01-02T15:08:45Z

Azure Pipelines successfully started running 1 pipeline(s).

jeet1995 · 2026-01-02T16:15:23Z

/azp run java - cosmos - tests

azure-pipelines · 2026-01-02T16:15:52Z

Azure Pipelines successfully started running 1 pipeline(s).

jeet1995 · 2026-01-03T00:03:17Z

/azp run java - cosmos - tests

azure-pipelines · 2026-01-03T00:03:43Z

Azure Pipelines successfully started running 1 pipeline(s).

jeet1995 added 2 commits December 4, 2025 10:05

Intercept 404-0s to remap to 404-1003s when parent resource is not fo…

09e9f58

…und.

Intercept 404-0s to remap to 404-1003s when parent resource is not fo…

6174bcc

…und.

github-actions bot added the Cosmos label Dec 26, 2025

jeet1995 added 5 commits December 29, 2025 10:35

Intercept 404-0s to remap to 404-1003s when parent resource is not fo…

049e707

…und.

Intercept 404-0s to remap to 404-1003s when parent resource for bulk …

0a22036

…operations.

Force client closure in finally-block.

120cb57

Clean up

2a50fa0

Reduce BridgeInternal#setSubstatusCode dependency.

3e8d85a

jeet1995 changed the title ~~Az cosmos remap sub status for doc requests against non existent container~~ Owner Resource Not Found: Fixes sub-status to 1003 for requests to child resources against non-existent container. Dec 29, 2025

jeet1995 marked this pull request as ready for review December 29, 2025 13:32

jeet1995 requested review from a team and kirankumarkolli as code owners December 29, 2025 13:32

Copilot AI review requested due to automatic review settings December 29, 2025 13:32

jeet1995 requested a review from a team as a code owner December 29, 2025 13:32

Copilot started reviewing on behalf of jeet1995 December 29, 2025 13:33 View session

Copilot AI reviewed Dec 29, 2025

View reviewed changes

jeet1995 added 3 commits December 29, 2025 18:25

Address review comments.

16bdc0b

Merge branch 'main' of https://github.com/jeet1995/azure-sdk-for-java …

2bf96dc

…into AzCosmos_RemapSubStatusForDocRequestsAgainstNonExistentContainer

Updated CHANGELOG.md

90c0ffc

xinlian12 reviewed Dec 29, 2025

View reviewed changes

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/StaleResourceRetryPolicy.java Outdated Show resolved Hide resolved

xinlian12 reviewed Dec 29, 2025

View reviewed changes

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/StaleResourceRetryPolicy.java Outdated Show resolved Hide resolved

xinlian12 reviewed Dec 29, 2025

View reviewed changes

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/StaleResourceRetryPolicy.java Outdated Show resolved Hide resolved

xinlian12 reviewed Dec 29, 2025

View reviewed changes

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/caches/RxCollectionCache.java Outdated Show resolved Hide resolved

Addressing review comments.

f52e657

jeet1995 added 3 commits December 30, 2025 12:40

Addressing review comments.

f80f506

Addressing review comments.

986a4df

Addressing review comments.

3b045a1

xinlian12 reviewed Dec 30, 2025

View reviewed changes

...mos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/caches/RxCollectionCache.java Outdated Show resolved Hide resolved

xinlian12 reviewed Dec 30, 2025

View reviewed changes

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java Outdated Show resolved Hide resolved

xinlian12 reviewed Dec 30, 2025

View reviewed changes

xinlian12 approved these changes Dec 30, 2025

View reviewed changes

Addressing review comments.

5943742

jeet1995 added 2 commits January 2, 2026 11:10

Addressing review comments.

45548e0

Addressing review comments.

3ffa5cb

Addressing review comments.

a4d5161

bigdaddykane18 approved these changes Jan 3, 2026

View reviewed changes


		CosmosException cosmosException = Utils.as(throwable, CosmosException.class);

		if (HttpConstants.StatusCodes.NOTFOUND == (cosmosException.getStatusCode())) {

Owner Resource Not Found (Gateway V2 Connection Mode and Direct Connection Mode): Remaps sub-status to 1003 for requests to child resources against non-existent container. #47604

Are you sure you want to change the base?

Owner Resource Not Found (Gateway V2 Connection Mode and Direct Connection Mode): Remaps sub-status to 1003 for requests to child resources against non-existent container. #47604

Uh oh!

Conversation

jeet1995 commented Dec 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Scenarios tested and fixed

All SDK Contribution checklist:

General Guidelines and Best Practices

Testing Guidelines

Uh oh!

jeet1995 commented Dec 26, 2025

Uh oh!

azure-pipelines bot commented Dec 26, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jeet1995 commented Dec 29, 2025

Uh oh!

azure-pipelines bot commented Dec 29, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jeet1995 commented Dec 30, 2025

Uh oh!

azure-pipelines bot commented Dec 30, 2025

Uh oh!

Uh oh!

Uh oh!

xinlian12 Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

jeet1995 Jan 2, 2026 • 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!

xinlian12 Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

jeet1995 Jan 2, 2026 • 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!

xinlian12 left a comment

Choose a reason for hiding this comment

Uh oh!

jeet1995 commented Jan 2, 2026

Uh oh!

azure-pipelines bot commented Jan 2, 2026

Uh oh!

jeet1995 commented Jan 2, 2026

Uh oh!

azure-pipelines bot commented Jan 2, 2026

Uh oh!

jeet1995 commented Jan 3, 2026

Uh oh!

azure-pipelines bot commented Jan 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

jeet1995 commented Dec 26, 2025 •

edited

Loading

jeet1995 Jan 2, 2026 •

edited

Loading

jeet1995 Jan 2, 2026 •

edited

Loading