{"record":{"id":"7572669a22f92b64","repo":"apache/pulsar","slug":"cannot-handle-messages-with-null-messages","errorCode":null,"errorMessage":"Cannot handle messages with null messages","messagePattern":"Cannot handle messages with null messages","errorType":"exception","errorClass":"PulsarClientException.InvalidMessageException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/ConsumerBase.java","lineNumber":449,"sourceCode":"\n    private static void validateMessageId(MessageId messageId) throws PulsarClientException {\n        if (messageId == null) {\n            throw new PulsarClientException.InvalidMessageException(\"Cannot handle message with null messageId\");\n        }\n    }\n\n    private static void validateMessageIds(List<MessageId> messageIdList) throws PulsarClientException {\n        if (messageIdList == null) {\n            throw new PulsarClientException.InvalidMessageException(\"Cannot handle messages with null messageIdList\");\n        }\n        for (MessageId messageId : messageIdList) {\n            validateMessageId(messageId);\n        }\n    }\n\n    private static void validateMessages(Messages<?> messages) throws PulsarClientException {\n        if (messages == null) {\n            throw new PulsarClientException.InvalidMessageException(\"Cannot handle messages with null messages\");\n        }\n        for (Message<?> message : messages) {\n            validateMessageId(message);\n        }\n    }\n    @Override\n    public void acknowledge(Message<?> message) throws PulsarClientException {\n        validateMessageId(message);\n        acknowledge(message.getMessageId());\n    }\n\n    @Override\n    public void acknowledge(MessageId messageId) throws PulsarClientException {\n        validateMessageId(messageId);\n        try {\n            acknowledgeAsync(messageId).get();\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();","sourceCodeStart":431,"sourceCodeEnd":467,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/ConsumerBase.java#L431-L467","documentation":"validateMessages(Messages<?>) rejects a null Messages collection with InvalidMessageException 'Cannot handle messages with null messages' before iterating elements. It is used by the batch-acknowledgment path consumer.acknowledge(Messages), so a null Messages object is rejected up front as a caller bug.","triggerScenarios":"Calling consumer.acknowledge((Messages<?>) null), typically when the Messages came from batchReceive() that was short-circuited, or a wrapper method forwards a null result.","commonSituations":"Storing the result of batchReceiveAsync().get() where an exception path yields null; conditional batch processing where the Messages variable is only assigned in one branch.","solutions":["Null-check the Messages object before calling acknowledge(Messages)","Ensure batchReceive() results are captured and validated before acking","Return an empty Messages instance instead of null from wrapper methods"],"exampleFix":"// before\nconsumer.acknowledge(pendingBatch); // may be null\n// after\nif (pendingBatch != null) {\n    consumer.acknowledge(pendingBatch);\n}","handlingStrategy":"validation","validationCode":"if (messages == null) {\n    return; // or throw IllegalArgumentException\n}","typeGuard":"boolean isAckableBatch(Messages<?> msgs) {\n    return msgs != null;\n}","tryCatchPattern":"try {\n    consumer.acknowledge(messages);\n} catch (PulsarClientException.InvalidMessageException e) {\n    log.warn(\"Invalid messages collection for ack: {}\", e.getMessage());\n}","preventionTips":["Always capture and check batchReceive()/batchReceiveAsync() results before acking","Assign Messages variables in all code branches or default to an empty Messages instance","Centralize batch ack in one helper that performs the null check"],"tags":["pulsar","acknowledgment","null-check","batch"],"backgroundTag":"null-message-argument","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}