How do I troubleshoot contact flow errors in Amazon Connect?

5 minute read
0

I want to investigate contact flows to identify which block within the contact flow follows the error branch.

Short description

For a tutorial on troubleshooting contact flow errors, see the Troubleshooting contact flow errors in Amazon Connect workshop.

To investigate and troubleshoot contact flows, you must have the following prerequisites:

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, use contact flow logs to troubleshoot failures and isolate where errors occur.

Contact flow exports

For exporting flow instructions, see How to import/export flows.

Use the exports to better understand the contact flows:

  • See how the call travels through the flow.
  • Correlate the contact flow logs.
  • Reproduce the issue in a sandbox environment.

Amazon CloudWatch metrics for Amazon Connect

For more information, see Monitoring your instance using CloudWatch.

Use the ContactFlowErrors and ContactFlowFatalError metrics for monitoring and troubleshooting events that are related to contact flows:

  • The ContactFlowFatalError metric indicates the number of times that a flow failed to run due to a system error. For example, an Amazon Connect outage.
  • The ContactFlowErrors metric indicates the number of times that the error branch runs for a contact flow.

To troubleshoot contact flow errors, query your CloudWatch Logs Insights to identify which block in the contact flow follows the error branch. Then, use the block to identify the root cause of the error.

Resolution

First, run a query to see related error events:

1.    Open the Amazon CloudWatch console.

2.    In the navigation pane, 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:

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

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

Then, to troubleshoot the contact flow error, review the following resources:

  • CloudWatch Alarm configuration detail to identify which metric (ContactFlowErrors or ContactFlowFatalError) configured the alarm and the alarm's associated contact flows. If the metric is ContactFlowFatalError, this might be a service issue as the flow failed to run due to a system error. If the metric configuring the alarm is ContactFlowErrors, this indicates a contact block was routed down the error branch.
  • Logs that are related to the impacted contact flow to identify which block produced the error. For more information on flow blocks, see Flow block definitions.

Sometimes, contact flow blocks produce errors to CloudWatch but they don't have corresponding CloudWatch logs. For a table of common contact blocks, see the Appendix in the Troubleshooting contact flow errors in Amazon Connect workshop.

AWS Lambda errors in contact flows

The most common errors in contact flows occur with the Invoke Lambda Function block. This contact flow block calls AWS Lambda, and optionally returns key-value pairs that you can use to set contact attributes.

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:1099999:function:Connect-Wallboard-Historical-Metrics",
    },
	"TimeLimit": "3000"
}

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

Access denied exceptions

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 indicates that the contact flow doesn't have access to invoke the Lambda function. For detailed steps on adding 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 verify 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 functions are correctly consumed when returned to Amazon Connect.

A contact flow error might occur due to multiple blocks. For more information on blocks and reason for errors, see the Appendix in the Troubleshooting contact flow errors in Amazon Connect workshop.


AWS OFFICIAL
AWS OFFICIALUpdated 2 years ago
3 Comments

Hi team,

I think there is a typo. "ContactID" vs "ContactId" i.e

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

should be

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

AWS
SUPPORT ENGINEER
kgopelo
replied a year ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
MODERATOR
replied a year ago

Thanks kgopelo, your comments saved my time. @AWS Official, Please fasten your review process.

profile picture
Shiva
replied 4 months ago