Skip to main content

Troubleshooting

Diagnostic Checklist​

Before troubleshooting specific issues, verify these prerequisites are met:

Prerequisites Checklist​

  • Named Credentials: User has access to required named credentials, all enabled for callouts with awsac namespace allowed
  • Lightning App Access: User has permission to access the Lightning app used for Omni-Channel
  • Lightning App Configuration: Amazon Connect for Salesforce utility item added with "Start automatically" enabled
  • Administrator Permissions: SCC Administrator permission set AND Contact Center Admin/Supervisor (Partner Telephony) permission set assigned
  • Agent Permissions: SCC Agent permission set AND Contact Center Agent (Partner Telephony) permission set assigned
  • Chat Permissions (required for all chat features):
    • Contact Center Bring Your Own Channel User permission set
    • Partner Messaging User license assignment
    • Customize Application system permission (added to SCC Agent permission set)
  • User Setup in Both Systems: User added to contact center in both Salesforce and Connect
  • SSO/SAML Configuration:
    • If using Salesforce IdP: Users added to SSO Connected App via profile or permission set
    • If using different IdP: Users properly added to the IdP
  • Omni-Channel Status: User set to Active status
  • Queue Mapping: User staffed on Omni-Queues that map to Connect queues with correct channels enabled

Severity Indicators​

Issues are marked with severity levels to help prioritize troubleshooting:

  • 🔴 Critical: Blocks functionality, commonly encountered during setup or operation
  • 🟡 Important: Impacts specific features or workflows
  • 🔵 Informational: Less common issues or specific edge cases

Setup​

🔴 Cannot Load SCC-AC Setup Page​

Symptom: Error message "Page doesn't exist" appears

Cause: Missing SCC Administrator permission set

Solution:

  1. Go to Salesforce Setup → Users → Permission Sets
  2. Assign SCC Administrator permission set to the user installing SCC-AC
  3. Refresh the page and try again

Related Documentation: Installing SCC-AC in Your Salesforce Organization, Step 2

🔴 "Assets version is not set" Error​

Symptom: Step "Enter AWS IAM User Credential" fails with error "Assets version is not set"

Cause: Missing SCC Administrator permission set

Solution:

  1. Verify SCC Administrator permission set is assigned to your user
  2. Log out and log back into Salesforce
  3. Retry the installation step

Related Documentation: Installing SCC-AC in Your Salesforce Organization, Step 2

🔴 "Enter imported certificate label" Failed​

Symptom: Certificate label step fails during setup

Cause: Certificate not properly imported or configured

Solution: Verify the following in order:

  1. Check certificate import:

    • Go to Setup → Certificate and Key Management
    • Confirm certificate is present

  2. Check S3 bucket:

    • Verify certificate exists in S3 bucket: sccac-{AWS-account-ID}-bucket-{Salesforce-Org-ID}

  3. Check AWS Secrets Manager:

    • Navigate to AWS Secrets Manager → SCCAC-Secret-orgId
    • Confirm CONNECTED_APP_CONSUMER_SECRET value has been updated

Salesforce Sandbox Refresh​

🔴 SCCAC Not Working After Sandbox Refresh​

Symptom: SCCAC stops functioning after performing a Salesforce sandbox refresh

Cause: Sandbox refresh changes critical org configurations including Organization ID, My Domain URL, and Service Cloud Voice settings

Solution: Uninstall and reinstall SCCAC following this guide: SCC-AC Setup After Sandbox Refresh

Authentication & Agent Status Sync​

🔴 Cannot Log Into SCV​

Symptom: Error "We can't log you in. Try refreshing your browser, or ask your Salesforce admin for help"

Cause: Incompatible AWS Connect features enabled

Solution:

  1. In AWS Connect console, navigate to your instance settings
  2. Disable the multi-IdP feature
  3. Disable multi-session support in AWS console
  4. Have the user log out and log back in

Why This Happens: These features require user interaction to select IdP/session, which prevents SCV's automated SSO flow in the hidden frame.

🔴 Agent Status Not Syncing​

Symptom: The "Amazon Connect for Salesforce" utility doesn't update to "Available" or "Offline" status even after clicking "Sync State"

Cause: Missing Trusted Domains configuration for Clickjack Protection

Solution:

  1. Add Trusted Domain:

    • Go to Setup → Session Settings
    • Search for "Trusted Domains for Inline Frames"
    • Click Add Domain

  2. Configure Domain:

    • Domain: *.force.com
    • IFrame Type: Visualforce pages
    • Click Save

  3. Verify:

    • Confirm *.force.com appears in the Trusted Domains list

    Trusted Domains Configuration

  4. Test:

Success Criteria: After clicking "Sync State", the utility should update to show "Available" or "Offline" status.

Messaging​

🟡 Lambda Failures During Inbound Contact Flow​

Symptom: Errors in Lambda execution logs during contact routing

Cause: Contact flow not properly configured with channel information

Solution:

  1. Open the contact flow in Amazon Connect
  2. Locate the "Set Contact Attributes" block (placeholder)
  3. Fill in the messaging channel's channel address identifier
  4. Save AND Publish the contact flow
  5. Test with a new contact

🟡 Messaging Session Shows Blank Content​

Symptom: Conversation transcript not visible in Messaging Session record page

Cause: Missing Enhanced Conversation widget

Solution:

  1. Go to Setup → App Manager
  2. Edit your Lightning app
  3. Add the Enhanced Conversation widget to the Messaging Session record page
  4. Save and refresh

🟡 Attachment Upload Returns 403 Error​

Symptom: Console log shows "403 AccessDeniedException" when calling start-attachment-upload

Cause: Missing S3 CORS configuration

Solution:

  1. Enable attachments in Connect:

    • Verify attachments feature is enabled in your Connect instance

  2. Configure S3 CORS:

    • Navigate to the attachments S3 bucket
    • Add CORS rules to allow access from Salesforce Visualforce domain
    • Include the awsac namespace in allowed origins

Example CORS Configuration:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST"],
    "AllowedOrigins": ["https://*.force.com"],
    "ExposeHeaders": []
  }
]

🔵 Attachment Upload Issues (General)​

Symptom: Attachments not uploading or displaying correctly

Possible Causes and Solutions:

ProblemCheckFix
Not represented as textTranscript shows embedded content instead of file.force.com URLVerify file upload handling logic
Unsupported file typeUser attempting to send .exe, .zip, etc.Only these file types are supported: .csv, .doc, .docx, .heic, .jfif, .jpeg, .jpg, .mov, .mp4, .pdf, .png, .ppt, .pptx, .rtf, .txt, .wav, .xls, .xlsx
File too largeAttachment >4MB (outbound) or >2MB (inbound)Limits: Outbound (agent→customer): 4MB, Inbound (customer→agent): 2MB
Attachments not set upMissing Connect configurationEnable attachments in Connect instance and configure S3 CORS
Scanning failuresAttachment scanning enabled in ConnectCheck that files pass the configured scanning process

🟡 Transfer Action Not Working​

Symptom: Unable to transfer chats or contacts

Cause: Missing quick connects or permissions

Solution:

  1. Verify Quick Connects:

  2. Verify Permissions: User must have ALL of these:

    • ✓ SCC Agent OR SCC Administrator
    • ✓ Contact Center Agent (Partner Telephony) OR Contact Center Administrator (Partner Telephony)
    • ✓ Partner Messaging User permission set license assignment
    • ✓ Contact Center Bring Your Own User permission set
    • ✓ Customize Application system permission (if not System Administrator profile)

How to Check: Setup → Users → [Select User] → Permission Set Assignments

🔵 Messaging Components Send as Plain Text​

Symptom: Formatted messaging components appear as plain text in Connect

Expected Behavior: This is currently working as designed.

Explanation: SCC-AC does not support messaging components. When sent from Salesforce, they are converted to their text fallback representation for compatibility with Connect.

🔴 "Invalid schema/topic" Error​

Symptom: Error message "Invalid schema/topic for topic: /event/awsac__SCC_Event__e"

Cause: SCRT2 Integration User missing SCC Events permission

Solution:

  1. Go to Setup → Users → Permission Sets
  2. Locate SCRT2 Integration User
  3. Add SCC Events read/write permission
  4. Test the integration

Related Documentation: Grant Required Permissions, Step 1

Cases​

🔵 Connect Task Not Created for Case​

Symptom: Case assigned to Omni-Queue but no Connect task contact created

Cause: Routing or Service Channel misconfiguration

Solution: Verify in order:

  1. Omni-Queue Configuration:

    • Go to Setup → Omni-Channel Settings → Queues
    • Confirm routing configuration mode is External Routing

  2. Service Channel:

    • Setup → Service Channels
    • Confirm Service Channel exists for Case objects

  3. Check AWS Logs:

    • Open AWS CloudTrail
    • Search for StartTaskContact requests
    • Review response for failure reasons

Success Criteria: Case assignment should trigger a task contact in Connect within a few seconds.

Routing/Omni​

🟡 Contact Routes but Agent Work Fails​

Symptom:

  • Contact routes to agent in Connect successfully
  • Agent work creation continually fails in Salesforce
  • Contact never presented to agent in Omni-Channel
  • Many AgentWork records created with Status=Unavailable

Cause: Missing prerequisites for Omni-Channel functionality

Solution: Verify ALL of the following:

  1. Agent Status:

    • Agent is "Available" in Omni-Channel
    • Not just showing as available but actually can receive work

  2. SSO Process:

    • Agent can log into Connect through Omni-Channel
    • Status syncs correctly between systems
    • No authentication errors in browser console

  3. Enhanced Omni-Channel:

Diagnosis Tip: Check browser console for JavaScript errors and review Omni-Channel supervisor logs for routing failures.

🔵 Agent Continually Set to Offline​

Symptom: Agent status automatically changes back to "Offline" immediately after being changed to another status (in CCP, via API, or in agent metrics)

Cause: Presence status missing required channel configuration

Solution:

  1. Check Presence Status Channels:

    • Setup → Omni-Channel Settings → Presence Statuses
    • Select the "Available" presence status
    • Verify it includes:
      • For chat contacts: Messaging AND Voice channels
      • For case contacts: Cases AND Voice channels

  2. Update if Necessary:

    • Edit the presence status
    • Add missing channels
    • Save changes

  3. Test:

    • Have agent set status to Available
    • Status should persist without reverting to Offline

🔵 Single Message Shows 100% Capacity​

Symptom: Agent receives one messaging session but Omni-Supervisor shows 100% of primary capacity consumed

Cause: Incorrect routing configuration model

Solution:

  1. Go to Setup → Omni-Channel Settings → Routing Configuration
  2. Change routing configuration to External Routing model
  3. Save and test with a new contact

Why This Matters: External Routing model allows Connect to manage capacity instead of Salesforce, enabling more accurate capacity calculations.

On Upgrades​

Permission Set Updates After Upgrade​

When upgrading to a new version of SCC-AC, new fields and objects may be added. This requires updating your permission sets.

Process:

1. Update SCC Administrator Permission Set​

Compare permissions between SCC Administrator and SCC Administrator Placeholder:

  • Object Settings
  • Apex Class Access
  • Visualforce Page Access
  • Named Credential Access
  • External Credential Principal Access
  • Custom Metadata Types

How to Compare:

  1. Setup → Permission Sets
  2. Open SCC Administrator Placeholder → Export permissions
  3. Open SCC Administrator → Export permissions
  4. Use a diff tool to compare
  5. Add missing permissions to SCC Administrator

2. Update SCC Agent Permission Set​

Repeat the same process comparing SCC Agent with SCC Agent Placeholder.

Quick Method:

  1. Setup → Permission Sets → SCC Administrator Placeholder
  2. Click "Manage Assignments" → "Edit"
  3. Note all enabled permissions
  4. Go to your SCC Administrator permission set
  5. Enable any missing permissions

Glossary​

Common Terms Used in Troubleshooting:

TermDefinition
awsac namespaceThe package namespace identifier for SCC-AC components
Partner TelephonySalesforce permission set category for telephony/voice integrations
SCRT2 Integration UserSystem user account for Service Cloud Real-Time integration
SSOSingle Sign-On - authentication method allowing one login for multiple systems
SAMLSecurity Assertion Markup Language - protocol used for SSO
IdPIdentity Provider - service that authenticates users (e.g., Salesforce, Okta)
CCPContact Control Panel - Amazon Connect's agent interface
Enhanced Omni-ChannelUpgraded Salesforce Omni-Channel with improved features
Quick ConnectAmazon Connect feature for transferring contacts to agents/queues/phone numbers
Clickjack ProtectionSecurity feature in Salesforce that prevents malicious iframe embedding

Need More Help?​

If your issue isn't covered here:

  1. Check the FAQ: Frequently Asked Questions
  2. Review Logs: Logs, Metrics & Alarms
  3. Check Release Notes: Salesforce Package Release Notes and AWS Resources Release Notes for known issues
  4. Contact Support: Provide:
    • Issue description
    • Steps to reproduce
    • Screenshots of error messages
    • Relevant log entries