Message 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.

Configure retries for TCP 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;
      }
  }