How do I troubleshoot contact flow errors in Amazon Connect?

Resolution

Turn on contact flow logs

Turn on flow logs. Use contact flow logs to understand how a call travels through the different blocks of the contact flow. Also, you can use contact flow logs to troubleshoot failures and isolate errors.

To see how the call travels through the flow, correlate the contact flow logs, or reproduce the issue in a sandbox environment, export your flows.

Identify your contact flow error

To monitor and identify contact flow errors, use the ContactFlowErrors and ContactFlowFatalError Amazon CloudWatch metrics.

To find error related events, complete the following steps:

1. Open the CloudWatch console.
2. In the navigation pane, under Logs, choose Log Insights.
3. Select the name of the log group for your Amazon Connect instance logs. The format is /aws/connect/yourinstancename.
4. In the upper right corner, specify a query timescale.
5. Run the following query for a specific time range:

   fields @timestamp, @message| filter @message like 'Results'
   | parse @message '"Results":"*","ContactId":"*","ContactFlowId":"*","ContactFlowName":"*","ContactFlowModuleType":"*"' as Results, ContactId, ContactFlowId, ContactFlowName, BlockType
   | filter Results like 'rror' or Results like 'ailed' or Results like 'imeout' or Results like 'xception' or Results like 'No prompt provided' or Results like 'Instance has reached concurrent Lambda thread access limit' or Results like 'nsupported' or Results like 'nvalid' or Results like 'not found' or Results like 'execution limit reached'
   | sort @timestamp asc
   | display Timestamp, Results, ContactId, ContactFlowId, ContactFlowName, BlockType

   -or-
   Run the following query for a specific contact ID:

   fields @timestamp, @message| sort @timestamp desc
   | filter ContactId = "162faf0b-4e68-4a4b-bbde-96c9631f2a95"

   Note: Replace the value for ContactId with your Contact ID.

To troubleshoot the contact flow error, review your CloudWatch alarm configuration details. Identify whether you used the ContactFlowErrors or ContactFlowFatalError metric to configure the alarm and the alarm's associated contact flows.

If the alarm metric is ContactFlowFatalError, then the error might be a service issue as the flow failed to run due to a system error. If the alarm metric is ContactFlowErrors, then this means that Amazon Connect routed a contact block down the error branch.

Then, review logs that are related to the affected contact flow to identify the block that produced the error. For more information on flow blocks, see Flow block definitions in the flow designer in Amazon Connect.

Note: Contact flow blocks might produce errors to CloudWatch, but not produce a corresponding CloudWatch log.

Troubleshoot Lambda errors in contact flows

The Invoke Lambda Function block calls AWS Lambda and optionally returns key-value pairs that you can use to set contact attributes. This block can cause contact flow errors.

To investigate Lambda function errors, run the following query in CloudWatch Logs Insights:

fields @timestamp, @message| sort @timestamp desc
| filter Results LIKE "Error"

The output looks similar to the following:

{
    "Results": "The Lambda Function Returned an Error.",
    "ContactId": "alebb22a-93c4-4f90-8f22-b3718c4578E0",
    "ContactFlowId": "contact-flow-id",
    "ContactFlowName": "chat",
    "ContactFlowModuleType": "InvokeExternalResource",
    "Timestamp": "2023-12-20T14:14:13.794Z",
    "Parameters": {
        "FunctionARN": "arn:aws:lambda:us-west-2:111122223333:function:Connect-Wallboard-Historical-Metrics",
    },
    "TimeLimit": "3000"
}

The affected ContactFlowModuletype of InvokeExternalResource, refers to a Lambda function, contact flow name, and error. Find the affected Lambda function. Then, correlate the timestamps, or contact ID, to get the exact event that caused the error in the Lambda execution logs.

The following is an example of an error in the contact flow logs that the InvokeExternalResource block causes:

{
    "Results": "Status Code: 403; Error Code: AccessDeniedException; RequestID: 435c21cc-19d8-4847-864e-e32867fe3a70
    "ContactId": "alebb22a-93c4-4f90-8f22-b3718c4578E0",
    "ContactFlowId": " arn:aws:lambda:us-west-2:1099999/contact-flow/65569e69-5c67-4061-8776-fd1d501c4838",
}

The "Access Denied" error means that the contact flow doesn't have access to invoke the Lambda function. For information about how to add a function to the instance, see Add a Lambda function to your Amazon Connect instance.

There isn't a RequestId that ties Amazon Connect log messages for contact flows with Lambda execution logs. If the Lambda functions print the invocation event, then use the ContactId to correlate the contact flow logs and Lambda function execution logs. If the function doesn't print the invocation event, then use the timestamp in the contact flow logs to filter the Lambda function's execution logs.

If the Invoke Lambda Function block returns an error but there isn't a corresponding entry in the Lambda functions, then check the following configurations:

• The Lambda Payload might be NULL.
• The output returned from the function must be a flat object of key and value pairs, with values that include alphanumeric, dash, and underscore characters.
• The Lambda function response isn't a simple string map, or the response is greater than 32k. It's a best practice to test the output returned from your Lambda function to confirm that Amazon Connect correctly consumes functions that Lambda returns.

To prevent contact flow errors, you can use Amazon Connect's native call simulation before you deploy the contact flow in production.