Amazon Cognito isn't delivering MFA text messages to my app's users. How do I troubleshoot this?

Last updated: 2020-04-22

When the users in my Amazon Cognito user pool sign in to my app, they don't receive a multi-factor authentication (MFA) text message with their one-time password (OTP) as expected. How do I troubleshoot these message delivery failures?

Short Description

Amazon Cognito's MFA SMS (text) messages are sent using Amazon Simple Notification Service (Amazon SNS). When SMS messages from Amazon SNS aren't delivered as expected, you can troubleshoot the delivery failure reason using Amazon CloudWatch Logs.

Delivery failure commonly occurs when an AWS account hits its monthly service quota for SMS spending. If your account hit that service quota, see how to request a service quota increase and then begin monitoring your account's SMS usage.

Resolution

If you haven't done so already, enable CloudWatch Logs for your SMS messages. Then, follow these instructions.

Review delivery logs using CloudWatch

Check the provider response logs of SMS deliveries in the CloudWatch console. In each delivery status log, the providerResponse attribute contains the reason for delivery success or failure.

Note: If you just now enabled CloudWatch Logs for SMS messages, you won't see logs of your account's past SMS usage from before you enabled logging.

As a test, you can use Amazon SNS to send an SMS message to your own mobile phone. If the test message doesn't arrive, check the logs for the provider response.

View the month-to-date SMS spending

Look at your account's Amazon SNS metrics to see the month-to-date SMS spending (SMSMonthToDateSpentUSD).

  1. Open the CloudWatch console.
  2. In the left navigation pane, choose Metrics.
  3. Under All metrics, choose SNS, and then choose Metrics with no dimensions.
  4. Under Metric Name, expand SMSMonthToDateSpentUSD, and then choose Graph this metric only.
    Note: On the Graphed metrics tab, confirm that Statistic is set to Maximum.
  5. In the graph, note the value of the metric.

For more information, see Graphing a Metric.

Check the monthly service quota for SMS spending

Look at your account's monthly Amazon SNS service quota for SMS spending. Compare it to your account's month-to-date SMS spending to determine if it hit the monthly quota.

  1. Open the Amazon SNS console.
  2. In the left navigation pane, choose Text messaging (SMS).
  3. Under Text messaging preferences, note the value for Account spend limit.

For more information, see Setting SMS messaging preferences and Amazon Simple Notification Service endpoints and quotas.

(Optional) Request a service quota increase for SMS spending

If your account hit the monthly Amazon SNS service quota for SMS spending, but you want to send more SMS messages, request a service quota increase. If you expect your monthly SMS usage to stay the same (or increase), a service quota increase also prevents the issue from happening again.

Set an alarm and monitor SMS usage

In addition to a service quota increase, keeping informed of your account's SMS activity can help you avoid hitting the monthly service quota. Do any of the following: