This topic describes the message retry mechanism and its configuration method in Message Queue for Apache RocketMQ.

Notice For Message Queue for Apache RocketMQ HTTP SDK, unordered messages are retried every 5 minutes, ordered messages are retried every 1 minute, and a maximum of 288 retries are allowed. The following sections apply only to the message retry mechanism of commercial TCP SDKs. For more information, see Commercial TCP SDKs.

Retries for ordered messages

If a consumer fails to consume an ordered message, Message Queue for Apache RocketMQ automatically retries sending the message continuously at an interval of one second. This may block message consumption. Therefore, when you use ordered messages, make sure that your application can promptly monitor and handle consumption failures to prevent blocking.

Retries for unordered messages

Unordered messages include normal, scheduled, delayed, and transactional messages. You can set a response code to trigger message retry if a consumer fails to consume such messages.

Retries of unordered messages take effect only in clustering consumption mode. If message consumption fails in broadcasting consumption mode, consumers do not attempt to consume failed messages a second time. Instead, they continue to consume new messages.

Notice The following information applies only to unordered messages.

Number of retries

Message Queue for Apache RocketMQ allows a maximum of 16 retries for each message by default. The following table lists the intervals for the retries.

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 a message fails to be consumed after 16 retries, it will not be delivered. Strictly based on the preceding intervals, if a message continuously fails to be consumed, the message is retried 16 times within 4 hours and 46 minutes. After this period of time, the message will not be delivered.

Notice The message ID of a retried message does not change regardless of the number of retries.

Configuration method

  • Retry after a message consumption failure

    Assume that retries are expected after a message consumption failure in clustering consumption mode. This must be configured in the implementation of the MessageListener operation in one of the following methods:

    • Method 1: Return Action.ReconsumeLater (recommended).
    • Method 2: Return null.
    • Method 3: Throw an exception.

    Sample code

    public class MessageListenerImpl implements MessageListener {
    
        @Override
        public Action consume(Message message, ConsumeContext context) {
            // The message processing logic throws an exception. The message will be retried.
            doConsumeMessage(message);
            // Method 1: Return Action.ReconsumeLater and retry the message.
            return Action.ReconsumeLater;
            // Method 2: Return null and retry the message.
            return null;
            // Method 3: Throw an exception and retry the message.
            throw new RuntimeException("Consumer Message exception");
        }
    }
  • Disable retries after a message consumption failure

    Assume that no retries are expected after a message consumption failure in clustering consumption mode. Exceptions thrown by the consumption logic must be caught, and Action.CommitMessage is returned. After this, the message will not be retried.

    Sample code

    public class MessageListenerImpl implements MessageListener {
    
        @Override
        public Action consume(Message message, ConsumeContext context) {
            try {
                doConsumeMessage(message);
            } catch (Throwable e) {
                // Catch all exceptions in the consumption logic and return Action.CommitMessage.
                return Action.CommitMessage;
            }
            // If message consumption does not fail, return Action.CommitMessage.
            return Action.CommitMessage;
        }
    }
  • Customize the maximum number of retries
    Note To customize the log configuration of your Message Queue for Apache RocketMQ client, you must update Message Queue for Apache RocketMQ TCP SDK for Java to version 1.2.2 or later.

    Message Queue for Apache RocketMQ allows you to set the maximum number of retries when the consumer is started. The following list describes how custom retry intervals are determined:

    • If the maximum number of retries is at most 16, the retry interval is as described in the preceding table.
    • If the maximum number of retries is greater than 16, the interval of the 17th and later retries is 2 hours.

    You can use the following the configuration method:

    Properties properties = new Properties();
    // Set the maximum number of message retries for the group ID to 20. The value is of the string type.
    properties.put(PropertyKeyConst.MaxReconsumeTimes,"20");
    Consumer consumer =ONSFactory.createConsumer(properties);
    Notice
    • The configuration of the maximum number of message retries applies to all consumer instances with the same group ID.
    • If MaxReconsumeTimes is set for only one of the two consumer instances with the same group ID, the configuration applies to both consumer instances.
    • The configuration of the last started consumer instance overwrites the configurations of previously started instances.

Obtain the number of retries

After a consumer receives a message, the consumer can obtain the number of retries in the following method:

public class MessageListenerImpl implements MessageListener {

    @Override
    public Action consume(Message message, ConsumeContext context) {
        // Obtain the number of retries.
        System.out.println(message.getReconsumeTimes());
        return Action.CommitMessage;
    }
}