Message retry

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.

Retry the consumption of messages sent over TCP

Ordered messages

Unordered messages

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

• 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;
      }
  }