Amazon Connect Routing Criteria Troubleshooting Guide: Complete Solutions for Common Issues

When implementing routing criteria in Amazon Connect, contact center administrators often encounter various issues that prevent contacts from being routed to agents with the appropriate skills. This comprehensive guide covers the most common problems and their solutions.

Routing Criteria Flow Overview

Issue 1: Generic "Error" Result in Contact Flow Logs

Problem: Contact flow logs show generic error without specific details, making it difficult to identify the root cause.

Contact Flow Log Output:

{
    "Results": "Error",
    "ContactId": "12345678-abcd-1234-efgh-123456789012",
    "ContactFlowId": "arn:aws:connect:us-east-1:123456789012:instance/12345678-1234-1234-1234-123456789012/contact-flow/87654321-4321-4321-4321-210987654321",
    "ContactFlowName": "Customer_Service_Queue",
    "ContactFlowModuleType": "UpdateContactRoutingCriteria",
    "Identifier": "87654321-1234-5678-9012-345678901234",
    "Timestamp": "2025-10-02T21:31:48.337Z",
    "Parameters": {
        "JsonParameter": "RoutingCriteria=$.External.routingCriteria"
    }
}

Root Cause: Amazon Connect provides limited error details for routing criteria failures, requiring systematic troubleshooting to identify the specific issue.

Solution: Use the master troubleshooting flow to systematically identify the specific root cause:

Systematic Troubleshooting Approach:

1. First, check if Lambda returns stringified JSON (Issue 2).
2. Second, verify predefined attributes exist (Issue 3).
3. Third, confirm proficiency levels are 1-5 (Issue 4).
4. Fourth, validate comparison operators (Issue 5).
5. Finally, review contact flow configuration.

Issue 2: Lambda Returning Stringified JSON

Problem: Lambda function returns routing criteria as stringified JSON instead of proper JSON object.

Contact Flow Log Output:

{
    "Results": "Error",
    "ContactFlowModuleType": "UpdateContactRoutingCriteria",
    "Parameters": {
        "JsonParameter": "RoutingCriteria=$.External.routingCriteria"
    }
}

Lambda Response (Incorrect - Stringified JSON):

{
    "MyRoutingCriteria": "{\"Steps\":[{\"Expression\":{\"AndExpression\":[{\"AttributeCondition\":{\"Name\":\"Language\",\"Value\":\"English\",\"ComparisonOperator\":\"NumberGreaterOrEqualTo\",\"ProficiencyLevel\":4}}]}},{\"Expression\":{\"AttributeCondition\":{\"Name\":\"Technology\",\"Value\":\"AWS Kinesis\",\"ComparisonOperator\":\"NumberGreaterOrEqualTo\",\"ProficiencyLevel\":2}}}]}"
}

Lambda Response (Correct - JSON Object):

{
    "MyRoutingCriteria": {
        "Steps": [
            {
                "Expression": {
                    "AndExpression": [
                        {
                            "AttributeCondition": {
                                "Name": "Language",
                                "Value": "English",
                                "ProficiencyLevel": 4,
                                "ComparisonOperator": "NumberGreaterOrEqualTo"
                            }
                        }
                    ]
                },
                "Expiry": {
                    "DurationInSeconds": 30
                }
            },
            {
                "Expression": {
                    "AttributeCondition": {
                        "Name": "Technology",
                        "Value": "AWS Kinesis",
                        "ProficiencyLevel": 2,
                        "ComparisonOperator": "NumberGreaterOrEqualTo"
                    }
                }
            }
        ]
    }
}

JSON Format Comparison:

Root Cause: Amazon Connect expects routing criteria as native JSON objects, not string representations.

Solution: Update Lambda function to return proper JSON object structure instead of stringified JSON.

Issue 3: Predefined Attribute Not Found

Problem: Routing criteria references non-existent attributes.

Contact Flow Log Output:

{
    "Results": "Error",
    "ContactFlowModuleType": "UpdateRoutingCriteria",
    "Parameters": {
        "JsonParameter": "RoutingCriteria=$.External.routingCriteria"
    }
}

Lambda Response Content:

{
    "routingCriteria": {
        "Steps": [{
            "Expression": {
                "AttributeCondition": {
                    "Name": "NonExistentSkill",
                    "Value": "CustomerService",
                    "ProficiencyLevel": 3,
                    "ComparisonOperator": "NumberGreaterOrEqualTo"
                }
            }
        }]
    }
}

Root Cause: The attribute "NonExistentSkill" doesn't exist in the Connect instance's predefined attributes.

Solution:

1. Navigate to Routing > Predefined attributes.
2. Create missing attributes with proper values.
3. Assign proficiencies to agents.
4. Use only existing attribute names in routing criteria.

Attribute Validation Flow:

Issue 4: Invalid Proficiency Levels

Problem: Using proficiency levels outside valid range (1-5)

Contact Flow Log Output:

{
    "Results": "Error",
    "ContactFlowModuleType": "UpdateRoutingCriteria",
    "Parameters": {
        "JsonParameter": "RoutingCriteria=$.External.skillRouting"
    }
}

Lambda Response Content (Incorrect):

{
    "skillRouting": {
        "Steps": [{
            "Expression": {
                "AttributeCondition": {
                    "Name": "CustomerService",
                    "Value": "Level1",
                    "ProficiencyLevel": 0,
                    "ComparisonOperator": "NumberGreaterOrEqualTo"
                }
            }
        }]
    }
}

Lambda Response Content (Correct):

{
    "skillRouting": {
        "Steps": [{
            "Expression": {
                "AttributeCondition": {
                    "Name": "CustomerService",
                    "Value": "Level1",
                    "ProficiencyLevel": 1,
                    "ComparisonOperator": "NumberGreaterOrEqualTo"
                }
            }
        }]
    }
}

Root Cause: Proficiency levels must be integers between 1-5. Values of 0 or greater than 5 are invalid.

Solution: Ensure all proficiency levels are within the valid range (1-5).

Proficiency Level Validation:

Issue 5: Incorrect Comparison Operators

Problem: Using wrong comparison operators for attribute types

Contact Flow Log Output:

{
    "Results": "Error",
    "ContactFlowModuleType": "UpdateRoutingCriteria",
    "Parameters": {
        "JsonParameter": "RoutingCriteria=$.External.techRouting"
    }
}

Lambda Response Content (Incorrect):

{
    "techRouting": {
        "Steps": [{
            "Expression": {
                "AttributeCondition": {
                    "Name": "Technology",
                    "Value": "AWS Lambda",
                    "ComparisonOperator": "StringEquals",
                    "ProficiencyLevel": 3
                }
            }
        }]
    }
}

Lambda Response Content (Correct):

{
    "techRouting": {
        "Steps": [{
            "Expression": {
                "AttributeCondition": {
                    "Name": "Technology",
                    "Value": "AWS Lambda",
                    "ComparisonOperator": "NumberGreaterOrEqualTo",
                    "ProficiencyLevel": 3
                }
            }
        }]
    }
}

Root Cause: Using string comparison operators instead of numeric operators for proficiency levels.

Valid Operators:

• NumberGreaterOrEqualTo - Most common for proficiency matching.
• NumberLessThanOrEqualTo - For maximum proficiency requirements.
• Range - For proficiency ranges with NOT conditions.

Solution: Use appropriate numeric comparison operators for proficiency-based routing.

Comparison Operator Selection:

Issue 6: Missing Agent Proficiencies

Problem: Agents don't have required proficiencies assigned.

Contact Flow Log Output:

{
    "Results": "Success",
    "ContactFlowModuleType": "UpdateRoutingCriteria",
    "RoutingCriteria": {
        "Steps": [{
            "Status": "Expired",
            "Expression": {
                "AttributeCondition": {
                    "Name": "Language",
                    "Value": "Spanish",
                    "ProficiencyLevel": 3
                }
            },
            "Expiry": {
                "DurationInSeconds": 30
            }
        }]
    }
}

Lambda Response Content:

{
    "languageRouting": {
        "Steps": [{
            "Expression": {
                "AttributeCondition": {
                    "Name": "Language",
                    "Value": "Spanish",
                    "ProficiencyLevel": 3,
                    "ComparisonOperator": "NumberGreaterOrEqualTo"
                }
            },
            "Expiry": {
                "DurationInSeconds": 30
            }
        }]
    }
}

Root Cause: No agents have Spanish language proficiency at level 3 or higher assigned to their profiles.

Solution:

1. Navigate to Users > User management.
2. Select agent and edit profile.
3. In Routing profile section, assign proficiencies.
4. Set appropriate proficiency levels (1-5) for each attribute.

Agent Proficiency Assignment Flow:

Issue 7: Routing Criteria Not Activated

Problem: Routing criteria set but not activated by queue transfer.

Contact Flow Log Output:

{
    "Results": "Success",
    "ContactFlowModuleType": "UpdateRoutingCriteria",
    "RoutingCriteria": {
        "Steps": [{
            "Status": "Inactive",
            "Expression": {
                "AttributeCondition": {
                    "Name": "CustomerService",
                    "Value": "Billing",
                    "ProficiencyLevel": 2
                }
            }
        }]
    }
}

Contact Flow Configuration Issue: Contact flow ends after "Set routing criteria" block without transferring to queue.

Root Cause: Missing Transfer to queue block after Set routing criteria. Routing criteria remains in "Inactive" status.

Solution: Ensure contact flow includes both blocks in sequence:

1. Set routing criteria block.
2. Transfer to queue block (activates routing criteria).
3. Routing criteria status changes from "Inactive" to "Active".

Routing Criteria Activation Flow:

Issue 8: Agent Queue Transfer Bypasses Routing Criteria

Problem: Routing criteria ignored when transferring to agent queues.

Contact Flow Log Output:

{
    "Results": "Success",
    "ContactFlowModuleType": "Transfer",
    "Parameters": {
        "QueueId": "arn:aws:connect:us-east-1:123456789012:instance/12345678-1234-1234-1234-123456789012/agent/agent-queue-id"
    }
}

Contact Flow Configuration: Transfer to queue block configured with agent queue instead of standard queue.

Root Cause: Per AWS documentation, routing criteria only works with standard queues, not agent queues. When transferring to agent queues, routing criteria is bypassed.

Solution:

1. Use standard queues instead of agent queues for proficiency-based routing.
2. Ensure queue ARN points to standard queue, not agent queue.
3. Configure agents' routing profiles to include the standard queue.

Queue Type Impact on Routing:

Issue 9: Expired Routing Steps

Problem: All routing steps expire before finding matching agents.

Contact Flow Log Output:

{
    "Results": "Success",
    "ContactFlowModuleType": "UpdateRoutingCriteria",
    "RoutingCriteria": {
        "Steps": [
            {
                "Status": "Expired",
                "Expression": {
                    "AttributeCondition": {
                        "Name": "Technology",
                        "Value": "AWS",
                        "ProficiencyLevel": 5
                    }
                },
                "Expiry": {
                    "DurationInSeconds": 10
                }
            },
            {
                "Status": "Expired",
                "Expression": {
                    "AttributeCondition": {
                        "Name": "Technology",
                        "Value": "AWS",
                        "ProficiencyLevel": 3
                    }
                },
                "Expiry": {
                    "DurationInSeconds": 20
                }
            }
        ]
    }
}

Lambda Response Content:

{
    "expertRouting": {
        "Steps": [
            {
                "Expression": {
                    "AttributeCondition": {
                        "Name": "Technology",
                        "Value": "AWS",
                        "ProficiencyLevel": 5,
                        "ComparisonOperator": "NumberGreaterOrEqualTo"
                    }
                },
                "Expiry": {
                    "DurationInSeconds": 10
                }
            },
            {
                "Expression": {
                    "AttributeCondition": {
                        "Name": "Technology",
                        "Value": "AWS",
                        "ProficiencyLevel": 3,
                        "ComparisonOperator": "NumberGreaterOrEqualTo"
                    }
                },
                "Expiry": {
                    "DurationInSeconds": 20
                }
            }
        ]
    }
}

Root Cause: Expiry times too short or no agents available with required proficiency levels.

Solution:

1. Increase expiry duration for routing steps.
2. Add fallback step without expiry.
3. Ensure agents have required proficiencies assigned.
4. Consider broader criteria in later steps.

Routing Step Progression:

Master Troubleshooting Flow

Best Practices

1. Attribute Management:

   • Use descriptive attribute names.
   • Limit to 500 values per attribute.
   • Follow naming pattern requirements.

2. Proficiency Assignment:

   • Regularly audit agent proficiencies.
   • Use consistent proficiency scales across teams.
   • Document proficiency level meanings.

3. Routing Step Design:

   • Start with specific requirements, broaden in later steps.
   • Set appropriate expiry times based on SLA requirements.
   • Include fallback step without expiry.

4. Testing:

   • Test routing criteria with sample contacts.
   • Monitor queue metrics for routing effectiveness.
   • Use contact flow logs for troubleshooting.

Limitations

• Maximum 8 attributes per AND condition.
• Maximum 3 OR conditions per routing step.
• Maximum 10 preferred agents per step.
• Routing criteria only works with standard queues.
• Generic error messages in contact flow logs.

References

• Amazon Connect Set Routing Criteria Documentation
• Create Predefined Attributes Documentation
• Set up Routing Based on Agent Proficiencies