How do I troubleshoot common errors with the import process in Amazon Cognito?

Short description

There are some errors that commonly occur during the Amazon Cognito import process. These errors might occur when you import users with either an AWS Lambda trigger or a .csv file.

The following errors commonly occur during user migration from an AWS Lambda trigger import:

• AccessDeniedException
• UserCodeSyntaxError
• ResourceNotFoundException
• ImportModuleError

The following errors commonly occur during user migration from a .csv file import:

• Unexpected headers
• Failed/skipped user
• Import job expired
• Invalid attribute value
• CloudWatch Logs role missing permission

When you use a Lambda trigger or .csv file to import into Amazon Cognito, Amazon CloudWatch Logs records any errors in a log. Search for these errors in your AWS account.Then, use the following steps to troubleshoot the error that relates to your use case.

Resolution

User migration Lambda trigger import errors

AccessDeniedException

This error occurs when the Lambda role is missing an AWS Identity and Access Management (IAM) permission to perform an Amazon Cognito action. For example, a AdminInitiateAuth role with missing permissions causes this error. The AccessDeniedException error looks similar to the following message:

An error occurred (AccessDeniedException) when calling the AdminInitiateAuth operation: User: arn:aws:sts::ACCOUNT_ID:assumed-role/TestingMigration-role/TestingMigration is not authorized to perform: cognito-idp:AdminInitiateAuth on resource: arn:aws:cognito-idp:eu-central-1:ACCOUNT_ID:userpool/eu-central-1_YYYYOOOO
    because no identity-based policy allows the cognito-idp:AdminInitiateAuth action

To resolve the AccessDeniedException error, complete the following steps:

1.    Open the IAM console.

2.    In the navigation pane, choose Roles, and then find the Lambda execution role.

3.    Choose the Permissions tab for the IAM role.

4.    Expand the permissions policy to view the permissions that are associated with the user.

5.    Make sure that the policy includes the following parameters:
cognito-idp:AdminInitiateAuth in the Actions list
Allow for Effect.

6.    If the policy doesn't include the parameters, then update the policy to include them.
-or-
Create a new policy that follows the parameters, and then attach the policy to the IAM role. For more information, see Editing customer managed policies (console).

UserCodeSyntaxError

This error occurs when there's an issue in your Lambda code. For example, an indentation issue causes this error.

The UserCodeSyntaxError error looks similar to the following message:

[ERROR] Runtime.UserCodeSyntaxError: Syntax error in module 'lambda_function': unexpected indent

To resolve this error, check for the correct syntax usage in your code.

ResourceNotFoundException

This error occurs when a resource that's referenced in your Lambda code isn't found in your account or AWS Region. For example, a missing Amazon Cognito app client that's referenced in your code causes this issue.

The ResourceNotFoundException error looks similar to the following message:

[ERROR] ResourceNotFoundException: An error occurred (ResourceNotFoundException) when calling the AdminInitiateAuth operation: User pool client 52rXXXXXXXXXXXXXXXXXXge does not exist.

To resolve this error, confirm that the resource in question exists in your account and Region. Then, make sure to correctly specify the ID, name, or Amazon Resource Name (ARN) in your Lambda code.

ImportModuleError

This error occurs when you try to import or reference a module that doesn't exist in your Lambda code.

The ImportModuleError error looks similar to the following message:

[ERROR] Runtime.ImportModuleError: Unable to import module 'lambda_function': No module named lambda_function

To resolve this error, confirm that the module that you're trying to import in your code doesn't include any typos or non-existent module references.

.csv file import errors

Unexpected headers

This error occurs when there's an issue with missing or wrongly formatted headers that are specified in your .csv file.

The Unexpected headers error looks similar to the following message:

The header in the CSV file does not match the expected headers. Use the GetCSVHeader API to get the expected headers.

To resolve this error, run the following command to get a list of the correct headers. In this command, USER_POOL_ID is the user pool that you import users to:

aws cognito-idp get-csv-header --user-pool-id "USER_POOL_ID"

You can also use the Amazon Cognito console to download the .csv file header. For more information, see Downloading the .csv file header (console).

To make sure that you format your headers correctly, keep the following points in mind:

• Include every .csv header, even if the users don't have values for the header.
• Put all headers in place, but you don't have to put them in a specified order.
• Some headers require values, such as cognito:username, cognito:mfa_enabled, email (if the user pool requires email), email_verified, phone_number, and phone_number_verified.

Failed or skipped user

This error occurs when there's an issue with duplicate user references, or when your .csv file is missing required fields. For example, duplicate email_verified references or a missing cognito:mfa_enabled field cause this error.

The Failed or skipped user error looks similar to the following message:

Too many users have failed or been skipped during the import.

To resolve this error, make sure to remove duplicate users from the .csv file and specify all required attributes. For more information, see Creating the user import .csv file.

Import job expired

This error occurs when you create a job, but don't start the job within 24–48 hours.

The Import job expired error looks similar to the following message:

The user import job has expired.

To resolve this issue, run the following command to start a user import job:

aws cognito-idp start-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"

You can also use the Amazon Cognito console to start the job. For more information, see Importing users from a .csv file (console).

Note: You can have only one import job active at a time for each account.

Invalid attribute value

This error occurs when an invalid value is specified for an attribute in your .csv file.

The Invalid Attribute value error looks similar to the following message:

The User Record contains an invalid value for [attribute].

To resolve this issue, check the specified values for the attribute. For more information about attribute values, such as the proper format for phone numbers, see User pool attributes.

CloudWatch Logs role missing permission

This error occurs when the CloudWatch Logs role that's specified for the .csv import process has one of the following issues:

• Missing permissions, such as create log group or streams
• Trust relationship policy with a principal that's not valid

The CloudWatch Logs role missing permission error looks similar to the following message:

The configured CloudWatch Logs role is missing permissions or has an invalid trust policy.

To resolve this issue, allow identity permissions for CloudWatch actions. Also, allow cognito-idp.amazonaws.com as the service principal in the trust relationship policy. For more information, see Creating the CloudWatch Logs IAM role.

---