Message Queue for Apache RocketMQ provides the message retry feature. If a consumer fails to consume a message, Message Queue for Apache RocketMQ retries to send the message to the consumer based on a message retry mechanism. Message Queue for Apache RocketMQ retries to send messages that are sent over TCP and HTTP based on different mechanisms. This topic describes the message retry mechanisms and how to configure retries.

Precautions

  • The ID of a message remains unchanged regardless of the number of retries.
  • Message Queue for Apache RocketMQ retries to send messages only in clustering consumption mode. If a consumer fails to consume a message in broadcasting consumption mode, Message Queue for Apache RocketMQ does not retry to send the message to the consumer. In this case, the consumer continues to consume new messages.

Message retry mechanisms

If a consumer fails to consume a message, Message Queue for Apache RocketMQ retries to send the message to the consumer after the specified retry interval is elapsed. If the consumer still fails to consume the message after the maximum number of retries is reached, Message Queue for Apache RocketMQ delivers the message to a dead-letter queue.

  • Retry interval: the amount of time for which Message Queue for Apache RocketMQ waits to resend the message to the consumer after the consumer fails to consume the message.
  • Maximum number of retries: the maximum number of times that Message Queue for Apache RocketMQ can resend the message to the consumer after the consumer fails to consume the message.
Message retry mechanisms vary based on message types. Message Queue for Apache RocketMQ supports ordered messages and unordered messages. Unordered messages include normal messages, delayed messages, scheduled messages, and transactional messages. The following table describes the message retry mechanisms.
Protocol Message type Retry interval Maximum number of retries Configuration method
TCP Ordered message The suspendTimeMillis parameter is used to specify the retry interval for ordered messages. Valid values: 10 to 30000. Unit: milliseconds. Default value: 1000. The default value specifies that ordered messages are resent at an interval of 1 second. The MaxReconsumeTimes parameter is used to specify the maximum number of retries for ordered messages. The value of this parameter does not have an upper limit. If you leave this parameter empty, the maximum number of retries is Integer.MAX. See Configure retries for TCP messages.
Unordered message The retry interval for unordered messages varies based on the number of retries. The retry interval ranges from 1 second to 2 hours. You cannot customize the retry interval for unordered messages.
  • If the maximum number of retries for a message does not exceed 16, the message is resent at a predefined interval. For more information, see Retry intervals for unordered TCP messages.
  • If the maximum number of retries for a message exceeds 16, the message is resent at a predefined interval for the first 16 retries. After the first 16 retries, the message is resent at an interval of 2 hours.
The MaxReconsumeTimes parameter is used to specify the maximum number of retries for unordered messages. Default value: 16. The value of this parameter does not have an upper limit. We recommend that you use the default value.
HTTP Ordered message 1 minute 288 The message retry method is predefined in the system and cannot be modified.
Unordered message 5 minutes 288 The message retry method is predefined in the system and cannot be modified.
Table 1. Retry intervals for unordered TCP messages
Retry number Interval Retry number Interval
1 10 seconds 9 7 minutes
2 30 seconds 10 8 minutes
3 1 minute 11 9 minutes
4 2 minutes 12 10 minutes
5 3 minutes 13 20 minutes
6 4 minutes 14 30 minutes
7 5 minutes 15 1 hour
8 6 minutes 16 2 hours

Configure retries for TCP messages

Notice You can use the following methods to configure retries for messages that fail to be consumed. In the following examples, TCP messages are used. This section does not provide the methods for configuring retries for HTTP messages.
  • Enable the message retry feature

    If you want Message Queue for Apache RocketMQ to retry to send a failed message in clustering consumption mode, use one of the following methods to implement the MessageListener method:

    • Method 1: Return Action.ReconsumeLater. We recommend that you use this method.
    • Method 2: Return null.
    • Method 3: Throw an exception.

    Sample code

    public class MessageListenerImpl implements MessageListener {
    
        @Override
        public Action consume(Message message, ConsumeContext context) {
            // If the message processing logic throws an exception, the message is resent. 
            doConsumeMessage(message);
            // Method 1: Return Action.ReconsumeLater and retry to send the message. 
            return Action.ReconsumeLater;
            // Method 2: Return null and retry to send the message. 
            return null;
            // Method 3: Throw an exception and retry to send the message. 
            throw new RuntimeException("Consumer Message exception");
        }
    }
  • Disable the message retry feature

    If you do not want Message Queue for Apache RocketMQ to retry to send a failed message in clustering consumption mode, configure the message consumption code to catch all exceptions that are thrown by the consumption logic and return Action.CommitMessage. This way, Message Queue for Apache RocketMQ does not retry to send the message.

    Sample code

    public class MessageListenerImpl implements MessageListener {
    
        @Override
        public Action consume(Message message, ConsumeContext context) {
            try {
                doConsumeMessage(message);
            } catch (Throwable e) {
                // Catch all exceptions that are thrown by the consumption logic, and return Action.CommitMessage.
                return Action.CommitMessage;
            }
            // Do not catch exceptions that are thrown by the consumption logic, and return Action.CommitMessage.
            return Action.CommitMessage;
        }
    }
  • Customize the retry interval and the maximum number of retries
    Note If you need to customize the logging configuration of your TCP-based Message Queue for Apache RocketMQ client, update Message Queue for Apache RocketMQ TCP client SDK for Java to version 1.2.2 or later. For more information, see Release notes.

    Message Queue for Apache RocketMQ allows you to customize the retry interval and the maximum number of retries when you start a consumer. You cannot customize retry intervals for unordered messages. For more information about the retry intervals for unordered messages, see Retry intervals for unordered TCP messages.

    The following sample code provides an example on how to customize the retry interval and the maximum number of retries for messages that consumers in a specified group can consume:

    Properties properties = new Properties();
    // Set the maximum number of retries to 20. The value must be a string. 
    properties.put(PropertyKeyConst.MaxReconsumeTimes,"20");
    // Set the retry interval to 3,000 milliseconds. The value must be a string. 
    properties.put(PropertyKeyConst.suspendTimeMillis,"3000");
    Consumer consumer = ONSFactory.createConsumer(properties);
    Notice The most recent configuration takes effect for the consumers in the same group. The configuration of the most recent consumer that is started overwrites the configurations of previous consumers. Make sure that all consumers in the same consumer group use the same configurations for the retry interval and the maximum number of retries. If all consumers in a consumer group do not use the same configurations for the retry interval and the maximum number of retries, the configurations for the consumers overwrite each other.
  • Query the number of initiated retries

    After a consumer receives a message, you can use the following method to query the number of initiated retries. In most cases, you do not need to query the retry interval.

    public class MessageListenerImpl implements MessageListener {
    
        @Override
        public Action consume(Message message, ConsumeContext context) {
            // Query the number of initiated retries. 
            System.out.println(message.getReconsumeTimes());
            return Action.CommitMessage;
        }
    }