How do I troubleshoot Amazon Cognito user migration Lambda trigger errors?

Resolution

The following are common errors that you might encounter when using the user migration Lambda trigger.

"An error occurred (InvalidParameterException) when calling the InitiateAuth operation: USER_PASSWORD_AUTH flow not enabled for this client"

This error occurs when the Amazon Cognito user pool's app client isn't configured to use the USER_PASSWORD_AUTH or ADMIN_USER_PASSWORD_AUTH flows. To resolve this error, before you add a user migration Lambda trigger, activate the USER_PASSWORD_AUTH or ADMIN_USER_PASSWORD_AUTH flows in your app client.

To turn on the USER_PASSWORD_AUTH or ADMIN_USER_PASSWORD_AUTH flow, select that authentication flow in your app client. Use these flows instead of the default USER_SRP_AUTH flow. Amazon Cognito sends a password to your Lambda function to verify your user authentication in the other directory.

"An error occurred (UserNotFoundException) when calling the InitiateAuth operation: Exception migrating user in app client <example_client_id>"

This error occurs when the Lambda function that's set as the user migration Lambda trigger doesn't have a correctly configured authorization policy. In this case, the policy doesn't permit the Amazon Cognito service account principal, cognito-idp.amazonaws.com, to invoke the Lambda function. For more information, see Using resource-based policies for Lambda.

This error also occurs when you don't set the Lambda function as the user migration Lambda trigger for your Amazon Cognito user pool. To resolve this error, make sure that you configure your Lambda function as the user migration Lambda trigger for your user pool.

"An error occurred (UserNotFoundException) when calling the InitiateAuth operation: Error during migration: invalid finalUserStatus"

This error occurs when you set the finalUserStatus to any value other than CONFIRMED. To resolve this error, change finalUserStatus to CONFIRMED so that the user doesn't need to perform additional actions before signing in.

The invalid messageAction or invalid desiredDeliveryMediums errors occur when the parameter value that the Lambda function returns to Amazon Cognito isn't an expected value. To resolve these errors, change the parameters to expected values. For information on request and response parameters, see Migrate user Lambda trigger parameters.

"An error occurred (UserNotFoundException) when calling the InitiateAuth operation: Attributes did not conform to the schema: <example_attribute>: Attribute does not exist in the schema"

This error occurs when an attribute that's included in the Lambda function response isn't an attribute in your Amazon Cognito user pool. To resolve this error, make sure that you return attributes that exist in your user pool's schema.

"Exception during user migration" -or- "UserMigration failed with error: <example error message>"

These errors appear on the Hosted UI page and can occur for any of the previously mentioned reasons.

Because these error messages are generic, it can be difficult to identify a specific reason for the error. To get more details about the error when you're migrating users with the hosted UI, run the following AWS Command Line Interface (AWS CLI) command:

$ aws cognito-idp initiate-auth --client-id <your-client-id>
    --auth-flow USER_PASSWORD_AUTH --auth-parameters "USERNAME=<username>,PASSWORD=<password>"

Note: Replace <your-client-id> with your client ID. Replace <username> with your user name. Replace <password> with your password.

Note: If you receive errors when running AWS CLI commands, make sure that you're using the most recent version of the AWS CLI.

The command invokes the user migration Lambda function. Any errors that are returned include detailed messages.

Related information

Importing users into user pools with a user migration Lambda trigger

Migrate user Lambda trigger

Example: Migrate a user with an existing password