SqsAsyncBatchManager: no SDK exception thrown in receiveMessage request if `ReceiveMessageRequest` maxNumberOfMessages exceeds 10

[tkhill-AWS]

Describe the bug

The SqsAsyncClient (non batch) throws an exception on the following call:

sqsAsyncClient.receiveMessage(
    ReceiveMessageRequest.builder()
        .queueUrl(queueUrl)
        .maxNumberOfMessages(11)
        .build()).join(); // Exception: software.amazon.awssdk.services.sqs.model.SqsException: Value 11 for parameter MaxNumberOfMessages is invalid. Reason: Must be between 1 and 10, if provided.

but the SqsAsyncBatchManager does not:

batchManager.receiveMessage(
    ReceiveMessageRequest.builder()
        .queueUrl(queueUrl)
        .maxNumberOfMessages(11)
        .build()).join(); // No exception thrown; the SDK silently accepts the value

Regression Issue

• Select this option if this issue appears to be a regression.

Expected Behavior

I expected the same exception to be thrown for the SqsAsyncBatchManager.

Current Behavior

The SDK silently accept the value greater than 10.

Reproduction Steps

Here's a Q Developer example:

package com.example.sqs;

import software.amazon.awssdk.services.sqs.SqsAsyncClient;
import software.amazon.awssdk.services.sqs.batchmanager.SqsAsyncBatchManager;
import software.amazon.awssdk.services.sqs.model.ReceiveMessageRequest;

/**
 * Demonstrates inconsistent validation behavior between SqsAsyncClient and SqsAsyncBatchManager
 * when maxNumberOfMessages > 10.
 * 
 * Expected: Both should throw an exception for invalid maxNumberOfMessages values
 * Actual: Only SqsAsyncClient validates, SqsAsyncBatchManager silently accepts invalid values
 */
public class SqsBatchManagerBugDemo {
    
    public static void main(String[] args) {
        final String queueUrl = "https://sqs.us-east-1.amazonaws.com/123456789012/test-queue";
        final int invalidMaxMessages = 15; // SQS limit is 10
        
        try (SqsAsyncClient sqsClient = SqsAsyncClient.create();
             SqsAsyncBatchManager batchManager = sqsClient.batchManager()) {
            
            System.out.println("Testing maxNumberOfMessages = " + invalidMaxMessages + " (exceeds SQS limit of 10)");
            System.out.println();
            
            // Test 1: SqsAsyncClient - should throw exception
            System.out.println("1. Testing SqsAsyncClient.receiveMessage():");
            try {
                sqsClient.receiveMessage(ReceiveMessageRequest.builder()
                        .queueUrl(queueUrl)
                        .maxNumberOfMessages(invalidMaxMessages)
                        .build()).join();
                System.out.println("   ✗ No exception thrown (unexpected)");
            } catch (Exception e) {
                System.out.println("   ✓ Exception thrown as expected: " + e.getCause().getClass().getSimpleName());
                System.out.println("     Message: " + e.getCause().getMessage());
            }
            
            System.out.println();
            
            // Test 2: SqsAsyncBatchManager - currently doesn't throw exception (bug)
            System.out.println("2. Testing SqsAsyncBatchManager.receiveMessage():");
            try {
                batchManager.receiveMessage(ReceiveMessageRequest.builder()
                        .queueUrl(queueUrl)
                        .maxNumberOfMessages(invalidMaxMessages)
                        .build()).join();
                System.out.println("   ✗ No exception thrown (this is the bug - should validate like SqsAsyncClient)");
            } catch (Exception e) {
                System.out.println("   ✓ Exception thrown: " + e.getCause().getClass().getSimpleName());
                System.out.println("     Message: " + e.getCause().getMessage());
            }
            
            System.out.println();
            System.out.println("Expected behavior: Both clients should throw the same validation exception");
            System.out.println("Actual behavior: Only SqsAsyncClient validates the parameter");
        }
    }
}

Possible Solution

Add the max. check on the batch manager.

Additional Information/Context

No response

AWS Java SDK version used

2.31.73

JDK version used

17

Operating System and version

MacOS

[debora-ito]

Hi @tkhill-AWS! I can reproduce, no exception in thrown when batch manager is used.

The SqsException is a server-side validation, so my guess is that BatchManager handles maxNumberOfMessages internally and doesn't send it in the request. I'll dig deeper.

[debora-ito]

@tkhill-AWS So, this is expected behavior.

For read APIs (like receiveMessage), BatchManager will use maxNumberOfMessages = 10 under the hood, it will always receive the max limit of messages per API call.

This is kind of implicit in the BatchOverrideConfiguration#maxBatchSize javadocs, but one need to figure that receiveMessage is an inbound request.

Maybe this information is too implicit. Does it help if we call it out in the documentation? If so, where do you suggest we add?