How do I troubleshoot Amazon SNS message delivery failures to Amazon SQS queues?

Resolution

Confirm that the SQS queue is subscribed to the SNS topic

Complete the following steps:

1. Open the Amazon SNS console.
2. In the navigation pane, choose Subscriptions, and then choose your SNS topic subscription.
3. In Details, verify that the Status is Confirmed.

If the status is Pending Confirmation, then confirm the subscription. If the status is Deleted, then recreate the deleted subscription.

For more information, see How can I get my Amazon SQS subscription to successfully receive a notification from my Amazon SNS topic?

Check CloudWatch metrics

Complete the following steps:

1. View Amazon CloudWatch metrics for the Amazon SNS metric NumberOfMessagePublished. This metric shows whether the service is publishing the event to the SNS topic. If the metric doesn't populate, then there's an issue with the AWS service or application that publishes messages to the SNS topic.
2. If the NumberOfMessagePublished metric is populated, then check the NumberOfNotificationsDelivered and NumberOfNotificationsFailed metrics. These metrics show whether the subscribing endpoints are successfully receiving messages from your Amazon SNS topic.
3. Check the NumberOfNotificationsFilteredOut metric for the number of messages that subscription filter policies rejected. If the NumberOfNotificationsFilteredOut metric shows data, then proceed to the Review SNS message filter policies section.

For more information, see Amazon SNS metrics.

Verify SQS queue permissions

To ensure that your SQS queue AWS Identity and Access Management (IAM) policy allows SNS to perform the sqs:SendMessage action, complete the following steps:

1. Open the Amazon SQS console.
2. In the navigation pane, choose Queues.
3. Select your queue, and then choose the Access policy tab.
4. Verify that the policy includes a statement similar to the following:

{
  "Effect": "Allow",
  "Principal": {
    "Service": "sns.amazonaws.com"
  },
  "Action": "SQS:SendMessage",
  "Resource": "arn:aws:sqs:region:account-id:queue-name",
  "Condition": {
    "ArnEquals": {
      "aws:SourceArn": "arn:aws:sns:region:account-id:topic-name"
    }
  }
}

Note: Replace region with your AWS Region and account-id with your AWS account ID. Replace queue-name with your SQS queue name, and topic-name with your SNS topic name.

If the policy is missing or incorrect, then update it with the preceding policy to grant SNS the required permissions.

Check if SQS queue has encryption activated

If your SQS queue has server-side encryption (SSE) activated, then verify that the AWS Key Management Service (AWS KMS) policy grants SNS the required permissions.

For more information, see Why aren't messages that I publish to my Amazon SNS topic getting delivered to my subscribed Amazon SQS queue that has server-side encryption activated?

Configure cross-account permissions

If your SNS topic and SQS queue are in different accounts, then verify that both accounts have the correct permissions configured.

The topic owner must grant the queue owner's account permission to subscribe to the topic. The queue owner must grant the SNS service permission to send messages to the queue.

For more information, see Sending Amazon SNS messages to an Amazon SQS queue in a different account.

Review SNS message filter policies

If you use subscription filter policies, and NumberOfNotificationsFilteredOut metric has data points, then verify that your message attributes match the filter policy criteria.

SNS applies filter policies to message attributes or the message body. SNS doesn't deliver messages that don't match the filter policy to the subscribed SQS queue.

Complete the following steps:

1. Open the Amazon SNS console.
2. In the navigation pane, choose Subscriptions, and then choose your SNS topic subscription.
3. Select your SQS queue subscription.
4. Choose the Subscription filter policy tab, and then review your filter policy.
5. Verify that your published messages include attributes that match the filter policy criteria.

For more information, see How do I troubleshoot subscription filter policy issues in Amazon SNS?

Configure delivery status logging

Delivery status logging provides detailed CloudWatch Logs entries for each message delivery attempt. Use the AWS Management Console to configure delivery status logging. Then, view the CloudWatch Logs log group for your SNS topic. Check the providerResponse attribute for SMS delivery failure reasons.

Configure a dead-letter queue for failed messages

Set up a dead-letter queue (DLQ) to capture messages that SNS can't deliver to your SQS queue after multiple retry attempts.

Complete the following steps:

1. Open the Amazon SNS console.
2. In the navigation pane, choose Subscriptions.
3. Select your SQS queue subscription, and then choose Edit.
4. Expand the Redrive policy (dead-letter queue) section.
5. Turn on Redrive policy.
6. For Dead-letter queue, enter the Amazon Resource Name (ARN) of an existing SQS queue to use as your DLQ.
7. Choose Save changes.

Note: The DLQ must be in the same account and Region as the subscription.

For more information, see Configuring an Amazon SNS dead-letter queue for a subscription.

Use a retry mechanism for status code errors

SNS automatically retries message delivery for server-side errors but not for client-side errors. If you receive a status code error, then build retry logic in your applications for requests that failed. AWS SDKs have a built-in retry mechanism.

Note: If you have configured a DLQ, then messages that failed because of client-side errors are sent to the DLQ.

For more information, see Amazon SNS message delivery retries.

Related information

Subscribing an Amazon SQS queue to an Amazon SNS topic

How can I get my Amazon SQS subscription to successfully receive a notification from my Amazon SNS topic?

Why didn't my encrypted SNS topic receive a notification from an AWS service?