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

Copilot · 2025-12-29T13:42:56Z

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

+                    }).onErrorMap(throwable -> {
+                            if (throwable instanceof CosmosException) {
+
+                                CosmosException cosmosException = Utils.as(throwable, CosmosException.class);
+
+                                if (!ResourceType.DocumentCollection.equals(request.getResourceType()) && com.azure.cosmos.implementation.Exceptions.isNotFound(cosmosException)) {
+                                    cosmosExceptionAccessor.setSubStatusCode(cosmosException, HttpConstants.SubStatusCodes.OWNER_RESOURCE_NOT_EXISTS);
+                                }
+
+                                return cosmosException;
+                            }
+
+                            return throwable;
+                        });


This error mapping logic is duplicated across multiple locations in this file (lines 95-108, 111-124, and 137-150). Consider extracting this into a private helper method to reduce duplication and improve maintainability.

…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).

xinlian12 · 2025-12-29T20:01:09Z

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

+                    })
+                    .onErrorMap(throwable -> {
+
+                        if (throwable instanceof CosmosException) {


hmm, not sure this is the place for status code remapping since this is a retry policy - feels this logic should belong to RxCollectionCache only

xinlian12 · 2025-12-29T20:01:55Z

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

+                                return cosmosException;
+                            }
+
+                            if (this.enclosingOperationTargetResourceType != null && !ResourceType.DocumentCollection.equals(this.enclosingOperationTargetResourceType) && Exceptions.isNotFound(cosmosException)) {


do we need to check sub-status code as well?

xinlian12 · 2025-12-29T20:02:25Z

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

+
+                            CosmosException cosmosException = Utils.as(throwable, CosmosException.class);
+
+                            if (this.request != null && !ResourceType.DocumentCollection.equals(this.request.getResourceType()) && Exceptions.isNotFound(cosmosException)) {


do we need sub-status code checking?

xinlian12 · 2025-12-29T20:03:32Z

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

                        Mono<DocumentCollection> collectionObs = this.getByNameAsync(metaDataDiagnosticsContext, resourceFullName, request.properties);
-                        return collectionObs.doOnSuccess(collection -> {
+                        return collectionObs.onErrorMap(throwable -> {
+                            return throwable;


revert the change here? there is no remapping of the error cases

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


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

		if (this.request != null && !ResourceType.DocumentCollection.equals(this.request.getResourceType()) && Exceptions.isNotFound(cosmosException)) {

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

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!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

jeet1995 commented Dec 29, 2025

Uh oh!

azure-pipelines bot commented Dec 29, 2025

Uh oh!

xinlian12 Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

xinlian12 Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

xinlian12 Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

xinlian12 Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jeet1995 commented Dec 26, 2025 •

edited

Loading