[BUG] CustomItemSerializer causes NullPointerException on ORDER BY queries

[samvaity]

Describe the bug
When a customItemSerializer is registered on CosmosClientBuilder, queries using ORDER BY fail with a NullPointerException. The issue is that the custom serializer is invoked during internal deserialization of OrderByRowResult, not just for the final application-level object.

Version: com.azure:azure-cosmos:4.70.0
Java: 21

Steps to reproduce:

1. Register a custom CosmosItemSerializer on CosmosClientBuilder
2. Execute a query: SELECT * FROM c ORDER BY c.id
3. The query fails during deserialization

Stack trace:
java.lang.NullPointerException: Cannot invoke Object.getClass() because object is null
at com.azure.cosmos.implementation.query.orderbyquery.OrderByRowResult.getPayload(OrderByRowResult.java:43)
at com.azure.cosmos.implementation.query.OrderByDocumentQueryExecutionContext.lambda(OrderByDocumentQueryExecutionContext.java:695)

Expected: The customItemSerializer should only be called for the final application-level object, not for internal Cosmos SDK structures like OrderByRowResult or Document.

[github-actions]

🎯 Agentic Issue Triage

Bug confirmed in com.azure:azure-cosmos — OrderByRowResult.getPayload() NPE when a custom CosmosItemSerializer is registered.

The root cause is a missing null check at OrderByRowResult.java:43. When a custom serializer is active, super.get("payload") can return null, causing object.getClass() to throw NullPointerException.

---

🔍 Root Cause Analysis

File: sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/query/orderbyquery/OrderByRowResult.java

Affected method: getPayload() — line 43:

final Object object = super.get("payload");
if (!ObjectNode.class.isAssignableFrom(object.getClass())) { // 💥 NPE when object == null

When a custom CosmosItemSerializer is registered on CosmosClientBuilder, it intercepts internal SDK deserialization — including for OrderByRowResult, which is an internal wrapper type. If super.get("payload") returns null (e.g., when the serializer does not produce a payload field for the internal type), calling object.getClass() immediately throws NullPointerException.

Call path:

1. OrderByDocumentQueryExecutionContext.java:695 iterates over feedOfOrderByRowResults
2. Calls orderByRowResult.getPayload() on each item
3. getPayload() dereferences a possibly-null object

🛠️ Suggested Fix

A minimal fix in OrderByRowResult.getPayload():

public Document getPayload() {
    if (this.payload != null) {
        return this.payload;
    }
    final Object object = super.get("payload");
    // Guard against null — can occur when a custom CosmosItemSerializer
    // is registered and interferes with internal SDK deserialization.
    if (object == null) {
        return new Document();
    }
    if (!ObjectNode.class.isAssignableFrom(object.getClass())) {
        Document document = new Document();
        document.set(Constants.Properties.VALUE, object);
        payload = document;
    } else {
        this.payload = super.getObject("payload", Document.class);
    }
    return payload;
}

A deeper fix would be to ensure that the custom serializer is bypassed for internal SDK types (e.g., OrderByRowResult, Document) and only invoked for application-level POJO deserialization. This would require reviewing how CosmosClientBuilder wires the custom serializer into the deserialization path used by internal query execution contexts.

📋 Reproduction Checklist

• Create a CosmosClient with a custom CosmosItemSerializer registered
• Insert at least one document in a container
• Execute SELECT * FROM c ORDER BY c.id (or any ORDER BY query)
• Observe NullPointerException at OrderByRowResult.getPayload()
• Confirm the same query works without the custom serializer registered

📌 Sub-tasks

• Add a null-guard in OrderByRowResult.getPayload() (short-term fix)
• Investigate whether the custom serializer path in CosmosClientBuilder / CosmosItemSerializer should skip internal SDK types like OrderByRowResult and Document (long-term fix)
• Add a unit/integration test with a custom CosmosItemSerializer + ORDER BY query to prevent regression
• Update CHANGELOG.md for azure-cosmos

📚 Helpful Resources

• azure-cosmos SDK source — sdk/cosmos/azure-cosmos/
• OrderByRowResult.java
• OrderByDocumentQueryExecutionContext.java
• [Azure Cosmos DB Java SDK docs]((docs.microsoft.com/redacted)
• [azure-cosmos API reference]((azure.github.io/redacted)
• [CosmosItemSerializer JavaDoc]((azuresdkdocs.blob.core.windows.net/redacted)

---

Routing: Tagging Cosmos SDK service owners — @kushagraThapar @pjohari-ms @TheovanKraay

Note

🔒 Integrity filter blocked 3 items

The following items were blocked because they don't meet the GitHub integrity level.

• #45521 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below [none:samvaity/azure-sdk-for-java].
• #48811 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below [none:samvaity/azure-sdk-for-java].
• #48702 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below [none:samvaity/azure-sdk-for-java].

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Agentic Triage for issue #12 · ● 374.6K · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@8e6d7c86bba37371d2d0eee1a23563db3e561eb5