Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

User Guide to Troubleshooting the Flex UI


Depending on the situation, there are many ways to troubleshoot errors and other issues that you may encounter while using the Flex UI. Read on to learn more about various errors you might see, and how you can use the Status Report (formerly known as Debugger UI) to generate Error Reports to help get your problems solved.

Are you a developer looking to build customized error monitoring and reporting instead? Check out the Developer Documentation instead!


Types of errors

types-of-errors page anchor

As you use the Flex UI, you may encounter errors from:

  • 3rd party packages (e.g. React, Redux, Material UI) and Twilio packages (e.g., Chat SDK, Sync SDK) used by the Flex UI
  • Custom plugins that you've built
  • the Flex UI itself

Errors from all these sources can significantly degrade Flex functionality or lead to other unexpected behaviors.

Fortunately, some of these issues are simple fixes (for example, by checking your network connection). Others will require help from admins, developers, or additional support. In each case, fixing an error starts by understanding its cause and getting any additional context about the issue.


Flex can notify you about errors in 3 different ways:

  • During Flex initialization with the error page
  • With an error notification
  • In the Status Report (introduced in Flex UI 1.32 )

Flex Initialization Errors

flex-initialization-errors page anchor
Initialize error message.

In most cases, if Flex is experiencing and issue, it will still be able to start up. If some of the services or components are not available during Flex initialization, it will start up in Degraded mode. However, some issues can also prevent Flex from initializing. These are mostly issues connected to connectivity or authentication or an ongoing incident with one of the Twilio services which is a critical component for Flex UI normal function.

If Flex UI fails to initialize, user will see the following error message and an option to retry or download a report with more details about the error.

Possible error messages:

  • "Log in failed. Please contact your administrator and try again later."
  • "We're not able to log you in right now - this might be due to an ongoing incident we're experiencing. Contact your administrator and try again later."

You can see a full list of all Twilio services, their statuses and ongoing incidents on Twilio Status Page(link takes you to an external page).

Flex platform relies on multiple Twilio services and components for it to function properly. Starting from Flex UI v 1.31 Flex UI will initialize with limited capabilities, even if some of the components like SDK's (TaskRouter, Conversations, Voice or Sync) are down. In case of disruptions in Twilio services, Flex User will be able to login to Flex and perform certain tasks that are still available. For example, in the case of Twilio Voice experiencing an incident, your agent will still be able to handle messaging tasks.

Users will see a notification informing them of a possible disruption in the normal work of Flex UI and they will be able to download a thorough report with error details and logs.

You can find the list of components that Flex UI relies on and can startup in degraded mode in our API reference(link takes you to an external page).

Plugin developers can also force degraded mode of each Flex UI component when developing and testing plugins, to make sure that plugins can handle disruptions gracefully. Check out our developer docs for error handling and debugging in Flex UI for more information.

Warning and Error notifications

warning-and-error-notifications page anchor

Flex handles a collection of common errors with custom, integrated error notifications. For these handled errors, like errors when dialing a phone number, Flex will display an error notification with an error code.

(information)

Info

Enable the Status Report

In order to use the Status Report, you'll need to enable it on the Feature Settings page(link takes you to an external page) within the Flex Admin dashboard for Flex UI v1.32 or higher.

This feature was previously known as the Debugger UI and was available in Public Beta from v1.25.

All other errors (unhandled errors) will be shown in the Status Report. You can open it by clicking the Status Report icon in the Main Header. If an unhandled error occurs, the icon will show a red badge.

The Status Report has three sections. The top of the panel displays a summary of the status of the Flex UI. It condenses the data from all other areas into an easy-to-read message that can help users understand the impact of any issues on the performance of the Flex UI.

StatusDescription
No issues detectedFlex UI is working normally. A user can still download a report if they wish to share logs from their session.
Operational, issues detectedThe Status Report has detected errors in the Flex UI, or one or more platform services are reporting issues. The user can continue to work but may encounter issues.
Operational, status unavailableThe status of platform services could not be loaded.

Platform Services will display incidents reported by the services that Flex uses to operate. Note that this is refreshed periodically, so it may take some time for all users to be notified of status changes.

Your App displays any errors detected while the Flex UI has been running. You can open the preview to see the full details in the log. To help with debugging issues, you can clear the log to remove the issues displayed. You can download more details of the encountered error(s) into a report. See Error Report for more details.

If no errors have happened in the current session, you can still download a report, which will contain your session data and last 1000 log lines. This is particularly useful if Flex is experiencing some unexpected behavior, but you're not seeing any errors.


Error reports can be downloaded when an error has occurred during Flex initialization, or at any point while running Flex (with or without errors). They contain the following details:

  • Summary of the Status Report
  • Details of any Platform service incidents at the time the report was generated
  • Last 1000 debug level log lines
  • For each error detected:

    • Full error description
    • Stack trace
    • Source of the error
    • User session data
(warning)

Warning

Client-side logs or errors are allowed to contain PII (Personally Identifiable Information) because they are transient and are not saved beyond a user session. By exporting them, however, PII is also exported and saved to the file. Please take proper precautions to protect your customers' data when saving and sharing this file.


_316
_316
# Twilio Flex Error report
_316
---
_316
_316
_316
## Error: "Failed to init Flex SDK"
_316
_316
### LOG LINE
_316
```
_316
29/09/2022, 16:38:04 - initFlexSDK: Failed to init Flex SDK
_316
_316
Original error:
_316
"FlexSDK Client is forced disabled. Failing initialisation"
_316
```
_316
_316
### STACK TRACE
_316
```
_316
Error: Failed to init Flex SDK
_316
at new n (https://private-assets.twilio.com/flex/dev-builds/releases/flex-ui/main-62e5ef568c695eb2e78a700b5958a35511eb3498/twilio-flex.min.js:157:17890)
_316
at e.createAndProcessError (https://private-assets.twilio.com/flex/dev-builds/releases/flex-ui/main-62e5ef568c695eb2e78a700b5958a35511eb3498/twilio-flex.min.js:157:21065)
_316
at https://private-assets.twilio.com/flex/dev-builds/releases/flex-ui/main-62e5ef568c695eb2e78a700b5958a35511eb3498/twilio-flex.min.js:1603:206918
_316
```
_316
_316
### DETAILS
_316
```
_316
{
_316
"message": "Failed to init Flex SDK",
_316
"wrappedError": "FlexSDK Client is forced disabled. Failing initialization",
_316
"context": "initFlexSDK",
_316
"type": "flexSDK",
_316
"severity": "normal",
_316
"twilioErrorCode": 45600
_316
}
_316
```
_316
_316
<details>
_316
<summary>WRAPPED ERROR</summary>
_316
_316
```
_316
message: FlexSDK Client is forced disabled. Failing initialization
_316
stack: Error: FlexSDK Client is forced disabled. Failing initialization
_316
at https://private-assets.twilio.com/flex/dev-builds/releases/flex-ui/main-62e5ef568c695eb2e78a700b5958a35511eb3498/twilio-flex.min.js:1603:206386
_316
```
_316
_316
</details>
_316
---
_316
_316
### SESSION DATA
_316
```
_316
{
_316
"config": {
_316
"language": "en-US",
_316
"colorTheme": {
_316
"baseName": "FlexLight",
_316
"light": true,
_316
"preset": {
_316
"id": "light-blue",
_316
"name": "Light Blue"
_316
},
_316
"overrides": {
_316
"MainHeader": {
_316
"Container": {
_316
"background": "#233659"
_316
}
_316
},
_316
"SideNav": {
_316
"Button": {
_316
"background": "#4F5E7A"
_316
},
_316
"Container": {
_316
"background": "#4F5E7A"
_316
}
_316
}
_316
}
_316
},
_316
"pluginService": {
_316
"enabled": true,
_316
"url": "https://flex.twilio.com/plugins?hosted=true"
_316
},
_316
"logLevel": "debug",
_316
"rejectPendingReservations": true,
_316
"initialDeviceCheck": true,
_316
"notifications": {
_316
"browser": true,
_316
"mode": "whenNotInFocus",
_316
"enabled": true
_316
},
_316
"enableClientCalling": false,
_316
"flexServiceUrl": "https://preview.twilio.com/Flex",
_316
"warmTransfers": {
_316
"enabled": true
_316
},
_316
"sdkOptions": {
_316
"insights": {
_316
"region": -us1",
_316
"productId": "flex_insights",
_316
"logLevel": "debug"
_316
},
_316
"voice": {
_316
"eventgw": "eventgw.twilio.com",
_316
"chunderw": "chunderw-vpc-gll.twilio.com",
_316
"debug": true
_316
},
_316
"flex": {
_316
"environmentConfig": {
_316
"twilioServiceLoginUrl": "https://flex.twilio.com/admin",
_316
"authServiceUrl": "https://iam.twilio.com/v1/Accounts",
_316
"region": -us1",
_316
"configServiceUrl": "https://flex-api.twilio.com/v1/Configuration"
_316
},
_316
"logger": {
_316
"level": "debug"
_316
}
_316
},
_316
"worker": {
_316
"wsServer": "wss://event-bridge-us1.twilio.com/v1/wschannels",
_316
"ebServer": "https://event-bridge-us1.twilio.com/v1/wschannels",
_316
"logLevel": "debug"
_316
},
_316
"chat": {
_316
"region": -us1",
_316
"logLevel": "debug"
_316
}
_316
},
_316
"chatOrchestrationServiceUrl": "https://preview.twilio.com/Flex/WebChannels",
_316
"sessionUrl": "https://flex.twilio.com/api/v1/Session",
_316
"baseQueueManagementUrl": "https://flex.twilio.com/api",
_316
"showSupervisorDesktopView": true,
_316
"debugMode": false,
_316
"flexConfigServiceUrl": "https://flex-api.twilio.com/v1/Configuration",
_316
"taskRouterUrl": "https://taskrouter.twilio.com",
_316
"version_compatibility": "yes",
_316
"theme": {},
_316
"version_message": "",
_316
"markdown": {
_316
"enabled": false,
_316
"mode": "readWrite"
_316
}
_316
}
_316
}
_316
```
_316
_316
<details>
_316
<summary>LOGS</summary>
_316
<pre>
_316
16:37:56 | info | Flex UI logger decorated
_316
16:37:57 | info | Manager: Creating manager. flex-ui version: 1.31.2 core-ui version: 0.57.0
_316
16:37:57 | log | Manager: Flex UI bundle type - "cdnBundledReact"
_316
16:37:57 | log | Manager: React version - "16.5.2"
_316
16:37:58 | info | Manager: loginHandler created
_316
16:37:58 | info | Manager: manager created
_316
16:37:59 | info | Manager: remote config received
_316
16:37:59 | log | Notification handler browser enabled=true
_316
16:37:59 | log | SessionState: setting degraded to false
_316
16:38:01 | info | Manager: features received
_316
16:38:01 | info | SessionState: ssoLogin
_316
16:38:01 | info | SessionState: initializing SDK clients
_316
16:38:04 | log | [2022-09-29 16:38:04.312] Flex SDK → TelemetryProcessor (DEBUG): Sending 1 telemetry events
_316
16:38:04 | log | [2022-09-29 16:38:04.313] Flex SDK → TelemetryClient (DEBUG): creating event group with name: rate_limiter
_316
16:38:04 | log | [2022-09-29 16:38:04.613] Flex SDK → TelemetryProcessor (DEBUG): Telemetry sent successfully
_316
16:38:04 | log | SessionState: setting degraded to true
_316
16:38:04 | log | Executing "beforeAddNotification" listeners with {"id":"DegradedModeActive","content":"DegradedWarning","type":"error","timeout":0,"recurrenceTimeout":300000,"closeButton":true,"actions":[{"type":"[Function]","key":null,"ref":null,"props":{"label":"DegradedNotificationOpenStatusPanelAction","onClick":"[Function]","notification":"[Object]"},"_owner":null}]}
_316
16:38:04 | log | Completed "beforeAddNotification" listeners with {"id":"DegradedModeActive","content":"DegradedWarning","type":"error","timeout":0,"recurrenceTimeout":300000,"closeButton":true,"actions":[{"type":"[Function]","key":null,"ref":null,"props":{"label":"DegradedNotificationOpenStatusPanelAction","onClick":"[Function]","notification":"[Object]"},"_owner":null}]}
_316
16:38:04 | log | Emitting "notificationAdded" event for {"id":"DegradedModeActive","content":"DegradedWarning","type":"error","timeout":0,"recurrenceTimeout":300000,"closeButton":true,"actions":[{"type":"[Function]","key":null,"ref":null,"props":{"label":"DegradedNotificationOpenStatusPanelAction","onClick":"[Function]","notification":"[Object]"},"_owner":null}]}
_316
16:38:04 | log | Received "notificationAdded" event with {"id":"DegradedModeActive","content":"DegradedWarning","type":"error","timeout":0,"recurrenceTimeout":300000,"closeButton":true,"actions":[{"type":"[Function]","key":null,"ref":null,"props":{"label":"DegradedNotificationOpenStatusPanelAction","onClick":"[Function]","notification":"[Object]"},"_owner":null}]}
_316
16:38:04 | log | InAppNotificationHandler handling notitification and notifying of change {"id":"DegradedModeActive","content":"DegradedWarning","type":"error","timeout":0,"recurrenceTimeout":300000,"closeButton":true,"actions":[{"type":"[Function]","key":null,"ref":null,"props":{"label":"DegradedNotificationOpenStatusPanelAction","onClick":"[Function]","notification":"[Object]"},"_owner":null}]}
_316
16:38:04 | log | Received "notificationAdded" event with {"id":"DegradedModeActive","content":"DegradedWarning","type":"error","timeout":0,"recurrenceTimeout":300000,"closeButton":true,"actions":[{"type":"[Function]","key":null,"ref":null,"props":{"label":"DegradedNotificationOpenStatusPanelAction","onClick":"[Function]","notification":"[Object]"},"_owner":null}]}
_316
16:38:04 | log | Flex event emitter: flexError [{"getLogTime":"[Function]","content":{"context":"initFlexSDK","type":"flexSDK","wrappedError":"[Object]","severity":"normal","twilioErrorCode":45600},"time":{},"sessionData":{"config":"[Object]","reactVersion":"16.5.2","bundleType":"cdnBundledReact","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36"},"logManagerTimestamp":"16:38:01"}]
_316
</pre>
_316
</details>
_316
_316
_316
_316
_316
_316
### APPLICATION STATUS
_316
Ongoing incident
_316
_316
Our services are currently experiencing disruption, which might affect your work. We're aware and trying to fix the issues. Contact your support team if you're experiencing problems.
_316
_316
_316
_316
### DEGRADED CLIENT
_316
FlexSDKClient is degraded
_316
### PLATFORM SERVICES
_316
No issues detected
_316
_316
_316
_316
_316
_316
_316
## General Session Information
_316
_316
### SESSION DATA
_316
```
_316
{
_316
"config": {
_316
"language": "en-US",
_316
"colorTheme": {
_316
"baseName": "FlexLight",
_316
"light": true,
_316
"preset": {
_316
"id": "light-blue",
_316
"name": "Light Blue"
_316
},
_316
"overrides": {
_316
"MainHeader": {
_316
"Container": {
_316
"background": "#233659"
_316
}
_316
},
_316
"SideNav": {
_316
"Button": {
_316
"background": "#4F5E7A"
_316
},
_316
"Container": {
_316
"background": "#4F5E7A"
_316
}
_316
}
_316
}
_316
},
_316
"pluginService": {
_316
"enabled": true,
_316
"url": "https://flex.twilio.com/plugins?hosted=true"
_316
},
_316
"logLevel": "debug",
_316
"rejectPendingReservations": true,
_316
"initialDeviceCheck": true,
_316
"notifications": {
_316
"browser": true,
_316
"mode": "whenNotInFocus",
_316
"enabled": true
_316
},
_316
"enableClientCalling": false,
_316
"flexServiceUrl": "https://preview.twilio.com/Flex",
_316
"warmTransfers": {
_316
"enabled": true
_316
},
_316
"sdkOptions": {
_316
"insights": {
_316
"region": -us1",
_316
"productId": "flex_insights",
_316
"logLevel": "debug"
_316
},
_316
"voice": {
_316
"eventgw": "eventgw.twilio.com",
_316
"chunderw": "chunderw-vpc-gll.twilio.com",
_316
"debug": true
_316
},
_316
"flex": {
_316
"environmentConfig": {
_316
"twilioServiceLoginUrl": "https://flex.twilio.com/admin",
_316
"authServiceUrl": "https://iam.twilio.com/v1/Accounts",
_316
"region": -us1",
_316
"configServiceUrl": "https://flex-api.twilio.com/v1/Configuration"
_316
},
_316
"logger": {
_316
"level": "debug"
_316
}
_316
},
_316
"worker": {
_316
"wsServer": "wss://event-bridge-us1.twilio.com/v1/wschannels",
_316
"ebServer": "https://event-bridge-us1.twilio.com/v1/wschannels",
_316
"logLevel": "debug"
_316
},
_316
"chat": {
_316
"region": -us1",
_316
"logLevel": "debug"
_316
}
_316
},
_316
"chatOrchestrationServiceUrl": "https://preview.twilio.com/Flex/WebChannels",
_316
"sessionUrl": "https://flex.twilio.com/api/v1/Session",
_316
"baseQueueManagementUrl": "https://flex.twilio.com/api",
_316
"showSupervisorDesktopView": true,
_316
"debugMode": false,
_316
"flexConfigServiceUrl": "https://flex-api.twilio.com/v1/Configuration",
_316
"taskRouterUrl": "https://taskrouter.twilio.com",
_316
"version_compatibility": "yes",
_316
"theme": {},
_316
"version_message": "",
_316
"markdown": {
_316
"enabled": false,
_316
"mode": "readWrite"
_316
}
_316
},
_316
"reactVersion": "16.5.2"
_316
}
_316
```
_316
_316
<details>
_316
<summary>LOGS</summary>
_316
_316
<pre>
_316
16:37:56 | info | Flex UI logger decorated
_316
16:37:57 | info | Manager: Creating manager. flex-ui version: 1.31.2 core-ui version: 0.57.0
_316
16:37:57 | log | Manager: Flex UI bundle type - "cdnBundledReact"
_316
16:37:57 | log | Manager: React version - "16.5.2"
_316
16:37:58 | info | Manager: loginHandler created
_316
16:37:58 | info | Manager: manager created
_316
16:37:59 | info | Manager: remote config received
_316
16:37:59 | log | Notification handler browser enabled=true
_316
16:37:59 | log | SessionState: setting degraded to false
_316
16:38:01 | info | Manager: features received
_316
16:38:01 | info | SessionState: ssoLogin
_316
16:38:01 | info | SessionState: initializing SDK clients
_316
16:38:04 | error | 29/09/2022, 16:38:04 - initFlexSDK: Failed to init Flex SDK
_316
_316
Original error:
_316
"FlexSDK Client is forced disabled. Failing initialisation"
_316
16:38:04 | error | Flex SDK failed to initialize. Telemetry events won't be enabled for this session
_316
16:38:04 | info | Subscribing to Signaling events ....
_316
16:38:04 | log | SessionState: setting degraded to true
_316
</pre>
_316
_316
</details>


Rate this page: