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.

Overview

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 elapses. If the consumer still fails to consume the message after the maximum number of retries allowed is reached, Message Queue for Apache RocketMQ delivers the message to a dead-letter queue.

  • Retry interval: the amount of time that Message Queue for Apache RocketMQ waits to resend the message to the consumer after the last time the consumer fails to consume the message.
  • Maximum number of retries allowed: 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.
Note The ID of the message remains unchanged regardless of the number of retries.
Message retry mechanisms vary based on message types. Message Queue for Apache RocketMQ supports ordered and unordered messages. Unordered messages are divided into the following types: normal messages, delayed messages, scheduled messages, and transactional messages. The following table describes the retry mechanisms.
Protocol Message type Retry interval Maximum number of retries allowed Configuration method
TCP Ordered message The suspendTimeMillis parameter specifies 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 every second. The MaxReconsumeTimes parameter specifies the maximum number of retries allowed 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 allowed is Integer.MAX. For more information, see Configure message retries.
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. Custom settings are not supported.
  • If the maximum number of retries allowed for a message does not exceed 16, the message is resent at the intervals described in the table that is provided in the "Retry intervals for unordered messages" section.
  • If the maximum number of retries allowed for a message is greater than 16, the message is resent at the intervals described in the table that is provided in the "Retry intervals for unordered messages" section for the first 16 retries. After the first 16 retries, the message is resent every 2 hours.
The MaxReconsumeTimes parameter specifies the maximum number of retries allowed 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 N/A
Unordered message 5 minutes 288 N/A

Retry the consumption of messages sent over TCP

Ordered messages

If a consumer fails to consume an ordered message, Message Queue for Apache RocketMQ automatically retries to send the message to the consumer until the message is consumed. The maximum number of retries allowed is specified by the MaxReconsumeTimes parameter. If you leave this parameter empty, the maximum number of retries allowed is Integer.MAX. The retry interval is specified by the suspendTimeMillis parameter. By default, the ordered message is resent every second.
  • If the MaxReconsumeTimes parameter is set and the message is still not consumed when the maximum number of retries allowed is reached, Message Queue for Apache RocketMQ delivers the message to a dead-letter queue.
  • If the MaxReconsumeTimes parameter is not set, a maximum of Integer.MAX retries can be initiated until the message is consumed.

Unordered messages

Notice Message Queue for Apache RocketMQ retries to send unordered messages only in clustering consumption mode. If a consumer fails to consume an unordered 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.
If a consumer fails to consume an unordered message, Message Queue for Apache RocketMQ retries to send the message to the consumer until the message is consumed. The maximum number of retries allowed is specified by the MaxReconsumeTimes parameter. By default, an unordered message is resent at most 16 times. If the message is still not consumed after 16 retries, Message Queue for Apache RocketMQ delivers the message to a dead-letter queue. The following table describes the intervals between the 16 retries. If the maximum number of retries allowed for a message is greater than 16, the message is resent at the intervals described in the following table for the first 16 retries. After the first 16 retries, the message is resent every 2 hours.
Table 1. Retry intervals for unordered 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

If an unordered message fails to be consumed and the maximum number of retries allowed is 16, the following conclusion is obtained based on the retry intervals in the preceding table: The message is resent at most 16 times within the next 4 hours and 46 minutes until the message is consumed. If the message is still not consumed after 16 retries, Message Queue for Apache RocketMQ delivers the message to a dead-letter queue.

Retry the consumption of messages sent over HTTP

Ordered messages

If a consumer fails to consume an ordered message, Message Queue for Apache RocketMQ retries to send the message to the consumer until the message is consumed. The message is resent every minute, and the maximum number of retries allowed is 288. If the message is still not consumed after 288 retries, Message Queue for Apache RocketMQ delivers the message to a dead-letter queue.

Unordered messages

If a consumer fails to consume an unordered message, Message Queue for Apache RocketMQ retries to send the message to the consumer until the message is consumed. The message is resent every 5 minutes, and the maximum number of retries allowed is 288. If the message is still not consumed after 288 retries, Message Queue for Apache RocketMQ delivers the message to a dead-letter queue.

Configure message retries

Notice You can use the following methods to configure retries for messages that have failed to be consumed. In the following examples, messages sent over TCP are used. The methods to configure retries for messages sent over HTTP are not provided in this section.
  • Enable retries after a message consumption failure

    If you need Message Queue for Apache RocketMQ to retry to send a failed message in clustering consumption mode, you must use one of the following configuration 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 retries after a message consumption failure

    If you do not need Message Queue for Apache RocketMQ to retry to send a failed message in clustering consumption mode, you must 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;
            }
            // Catch no exceptions thrown by the consumption logic and return Action.CommitMessage.
            return Action.CommitMessage;
        }
    }
  • Customize the retry interval and the maximum number of retries allowed
    Note If you need to customize the log configuration of your TCP-based Message Queue for Apache RocketMQ client, update Message Queue for Apache RocketMQ TCP-based 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 allowed when consumers are started. However, you cannot customize the retry intervals for unordered messages. For more information about the retry intervals for unordered messages, see the "Retry intervals for unordered messages" section.

    The following sample code provides an example on how to customize the retry interval and the maximum number of retries allowed:

    Properties properties = new Properties();
    // Set the maximum number of retries allowed for messages consumed by consumers in the specified group to 20. The value is of the STRING type. 
    properties.put(PropertyKeyConst.MaxReconsumeTimes,"20");
    // Set the retry interval for messages consumed by consumers in the specified group to 3,000 milliseconds. The value is of the STRING type. 
    properties.put(PropertyKeyConst.suspendTimeMillis,"3000");
    Consumer consumer = ONSFactory.createConsumer(properties);
    Notice For consumers in the same group, the latest configuration takes effect. The configuration for the last started consumer overwrites the configurations for previously started consumers. Therefore, make sure that all consumers in a consumer group share the same settings of the retry interval and the maximum number of retries allowed. Otherwise, the configurations for the consumers will 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. Generally, 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;
        }
    }