{"record":{"id":"6e8531f36f4a3cbf","repo":"apache/rocketmq","slug":"messagelistener-is-null","errorCode":null,"errorMessage":"messageListener is null","messagePattern":"messageListener is null","errorType":"validation","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java","lineNumber":1084,"sourceCode":"        // allocateMessageQueueStrategy\n        if (null == this.defaultMQPushConsumer.getAllocateMessageQueueStrategy()) {\n            throw new MQClientException(\n                \"allocateMessageQueueStrategy is null\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        // subscription\n        if (null == this.defaultMQPushConsumer.getSubscription()) {\n            throw new MQClientException(\n                \"subscription is null\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        // messageListener\n        if (null == this.defaultMQPushConsumer.getMessageListener()) {\n            throw new MQClientException(\n                \"messageListener is null\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        boolean orderly = this.defaultMQPushConsumer.getMessageListener() instanceof MessageListenerOrderly;\n        boolean concurrently = this.defaultMQPushConsumer.getMessageListener() instanceof MessageListenerConcurrently;\n        if (!orderly && !concurrently) {\n            throw new MQClientException(\n                \"messageListener must be instanceof MessageListenerOrderly or MessageListenerConcurrently\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        // consumeThreadMin\n        if (this.defaultMQPushConsumer.getConsumeThreadMin() < 1\n            || this.defaultMQPushConsumer.getConsumeThreadMin() > 1000) {\n            throw new MQClientException(","sourceCodeStart":1066,"sourceCodeEnd":1102,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L1066-L1102","documentation":"checkConfig() requires a message listener before start. The listener is the callback that receives messages; without it the push consumer cannot deliver, so startup is rejected when getMessageListener() returns null.","triggerScenarios":"Calling start() without setMessageListener(...); registering the listener on a different consumer object than the one started (copy-paste bug); listener injection in DI returning null because the bean is missing.","commonSituations":"Quick-start code that forgets registerMessageListener; Spring configuration where the listener bean name is misspelled; refactoring that moved the listener setup behind a flag that is off.","solutions":["Call consumer.registerMessageListener(new MessageListenerConcurrently/Orderly(){...}) before start()","If using Spring, verify the listener bean resolves (no null injection)","Centralize consumer construction in one factory so subscribe + listener + start always happen together"],"exampleFix":"// before\nDefaultMQPushConsumer c = new DefaultMQPushConsumer(\"g\");\nc.subscribe(\"t\", \"*\");\nc.start(); // no listener\n\n// after\nc.registerMessageListener((MessageListenerConcurrently) (msgs, ctx) -> ConsumeConcurrentlyStatus.CONSUME_SUCCESS);\nc.start();","handlingStrategy":"validation","validationCode":"Objects.requireNonNull(listener, \"messageListener required\");\nconsumer.registerMessageListener(listener);","typeGuard":"boolean isSupportedListener(Object l) {\n    return l instanceof MessageListenerConcurrently || l instanceof MessageListenerOrderly;\n}","tryCatchPattern":null,"preventionTips":["Register the listener in the same factory method that subscribes and starts","Verify DI listener beans resolve non-null at context startup"],"tags":["rocketmq","config","listener","validation"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}