[Bug] azure-cosmos SDK 4.79.0 throws NullPointerException with emulator - "nRegionSynchronousCommitEnabled" is null

[azasypkin]

Description

The azure-cosmos Java SDK 4.79.0 (released 2026-03-27) added support for the N-Region synchronous commit feature (PR #47757). When using this SDK version against the emulator, any document creation operation throws a NullPointerException because the emulator response doesn't include the nRegionSynchronousCommitEnabled field, and the SDK attempts to unbox a null Boolean to a primitive boolean.

This makes the emulator unusable with azure-cosmos 4.79.0.

Environment

• Emulator image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-EN20260227
• SDK: com.azure:azure-cosmos:4.79.0
• Java: 21
• OS: macOS / Linux (Docker)

Steps to Reproduce

1. Start the emulator (requires proper CA setup):

docker run -d --name cosmos-emulator \
  -p 127.0.0.1:8081:8081 \
  -e AZURE_COSMOS_EMULATOR_PARTITION_COUNT=1 \
  -e AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE=false \
  -e GATEWAY_PUBLIC_ENDPOINT=localhost \
  -e LOG_LEVEL=error \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-EN20260227 \
  --protocol https --port 8081

2. Wait for the emulator to be ready, then install the emulator certificate into the JDK's default trust store (reference):

openssl s_client -connect localhost:8081 </dev/null 2>/dev/null \
  | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/cosmos_emulator.cert

keytool -cacerts -importcert -alias cosmos_emulator \
  -file /tmp/cosmos_emulator.cert -storepass changeit -noprompt

3. Create a minimal Maven project with this pom.xml:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>test</groupId>
  <artifactId>cosmos-repro</artifactId>
  <version>1.0</version>
  <properties>
    <maven.compiler.release>21</maven.compiler.release>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-cosmos</artifactId>
      <version>4.79.0</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.6.3</version>
        <configuration>
          <mainClass>ReproNpe</mainClass>
          <systemProperties>
            <systemProperty>
              <key>io.netty.handler.ssl.noOpenSsl</key>
              <value>true</value>
            </systemProperty>
          </systemProperties>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

4. Create this minimal Java program:

import com.azure.cosmos.*;
import com.azure.cosmos.models.*;

public class ReproNpe {
    public static void main(String[] args) {
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("https://localhost:8081")
            .key("C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==")
            .gatewayMode()
            .buildClient();

        client.createDatabaseIfNotExists("testdb");
        CosmosDatabase database = client.getDatabase("testdb");

        CosmosContainerProperties props = new CosmosContainerProperties("testcontainer", "/id");
        database.createContainerIfNotExists(props);
        CosmosContainer container = database.getContainer("testcontainer");

        container.createItem(new TestItem("1", "hello"));
        System.out.println("Success!");
    }

    public record TestItem(String id, String value) {}
}

5. Run: mvn compile exec:java

Expected Behavior

The document is created successfully, as it does with azure-cosmos 4.78.0 and earlier.

Actual Behavior

NullPointerException thrown from inside the SDK:

java.lang.NullPointerException: Cannot invoke "java.lang.Boolean.booleanValue()" because "nRegionSynchronousCommitEnabled" is null
    at com.azure.cosmos.implementation.DocumentServiceRequestContext.setNRegionSynchronousCommitEnabled(DocumentServiceRequestContext.java:279)
    at com.azure.cosmos.implementation.RxDocumentClientImpl.lambda$createDocumentInternal$57(RxDocumentClientImpl.java:2776)
    ...

Notes

• Works with azure-cosmos 4.78.0 - change the pom version to 4.78.0 and the same program succeeds
• The N-Region synchronous commit feature was introduced in 4.79.0 but the SDK doesn't handle the case where the emulator doesn't return the nRegionSynchronousCommitEnabled field
• This is likely also an SDK bug (null Boolean should be handled gracefully)

[azasypkin]

This is likely also an SDK bug (null Boolean should be handled gracefully)

Filed in SDK repo as well: Azure/azure-sdk-for-java#48630

[xgerman]

My Ai says:

✅ Already fixed — no longer reproducible

Latest MCR image (EN20260331, Mar 31) includes enableNRegionSynchronousCommit: false in the account metadata
response (GET /). This is all the Java SDK needs to avoid the NPE.

Analysis of the bug:

• The NPE occurred because the emulator didn't return enableNRegionSynchronousCommit in account metadata
• The SDK's DatabaseAccount.isNRegionSynchronousCommitEnabled() reads this field and defaults to false when
  missing — so the current main branch SDK handles it gracefully
• But an earlier snapshot (possibly the
  4.79.0-beta the reporter was using) may have had a Boolean → boolean unboxing issue before null safety was
  added

Current state of both sides:

• Emulator: Returns enableNRegionSynchronousCommit: false ✅
• SDK (main): GlobalEndpointManager.getNRegionSynchronousCommitEnabled() returns primitive boolean, handles null
  account → false ✅

The issue was likely a combination of (1) missing field in an older emulator image and (2) insufficient null
handling in a pre-release SDK build. Both sides have since been fixed. Note: SDK 4.79.0 isn't on Maven Central
yet (latest is 4.71.0), so the reporter was likely using an internal/preview build

[azasypkin]

Hey @xgerman,

Thanks for the heads-up - yes, I can confirm that our tests are passing with EN20260331 and the latest com.azure:azure-cosmos:4.79.0 SDK as well (the SDK team seems to have fixed this on their end in Azure/azure-sdk-for-java#48656 as well, but it's not yet released).

Thanks, and feel free to close this issue!