Skip to main content

Troubleshooting

Start with the app's status window (click the tray icon, or Show Window in the tray menu). Its activity log and the tray tooltip show what the app is doing. Errors from the recorder are also sent to Flex.

"The screen recorder app is not running on this computer"​

Flex shows this when an agent accepts a task and can't reach the app.

  • Start Flex Screen Recorder and check that its icon is in the tray.
  • The app listens for Flex on a local port (9876) on the agent's computer. If another program uses that port, the window says the connection server failed to start: close that program and restart the app.
  • Flex must be opened at https://flex.twilio.com. The app refuses connections from anywhere else (it closes them with "Origin not allowed").
  • Browser extensions or security software that block the browser from connecting to the local computer stop the plugin from reaching the app. Allow the connection for Flex.

After the app starts, the plugin connects again on its own (every 5 seconds, up to 10 attempts, and again on the next accepted task). Refreshing Flex also reconnects.

No "Recording" status in the Flex header​

The header status only appears while the plugin is connected to the app.

  • Check that screen_recording.enabled is true in the Flex configuration.
  • Check the recording policy: selective recording may exclude the task's channel or queue.
  • If agent opt-out is allowed, the agent may have switched recording off. The choice is saved in the browser and needs a Flex refresh to change.

The app shows "Not Configured" or "API Error"​

  • Not Configured: the app hasn't received the address of the Floor Walker service yet. It arrives from Flex when the plugin connects. Open Flex and check that screen_recording.api_url is set in the Flex configuration.
  • API Error: the app could not reach the Floor Walker service or was refused. Check that the agent's computer can reach the service over HTTPS (including through proxies and firewalls), and that the agent is signed in to Flex. If the agent's Flex session has expired, refresh Flex.

Uploads fail or segments are missing​

  • The app uploads to the Floor Walker service as it records. The service must be reachable from the agent's computer, including through proxies and firewalls.
  • Uploads are not retried. A part that fails to upload is missing from the recording, and the activity log shows the error.
  • If uploads fail for many agents at once, contact support.

Recording stopped by itself​

  • "the connection to the screen recorder was lost": Flex was closed, reloaded or lost its connection for more than 30 seconds while recording. Keep the Flex tab open during tasks.
  • "stopped after reaching the maximum length (1 hour)": sessions are limited to one hour. The recording up to that point is kept. If the agent still has tasks open, recording does not restart on its own until the next task is accepted.

Recording fails to start or "FFmpeg exited unexpectedly"​

FFmpeg is the recording component built into the app.

  • "FFmpeg not found. Screen recording is unavailable": reinstall the app.
  • macOS: the app needs the Screen Recording permission (System Settings, Privacy and Security, Screen Recording). Turn it on and restart the app.
  • Audio device: the app records audio from virtual-audio-capturer on Windows and the first audio device on macOS. If the device can't be opened, recording stops. See Audio capture.

Playback problems​

  • The recording doesn't load: the player's links to the recording are valid for an hour. Close and reopen the player to get fresh links. If it still fails, the media may have passed the retention period.
  • A recording is missing from the list: recordings appear only after the session is completed, that is after the agent's last open task is completed. A session cut off by a crash or power loss is not listed.
  • Jumps in the video: expected after a pause. Paused time is not recorded.

High CPU use​

The app records at a low frame rate tuned for screen content and uses the computer's graphics hardware when it can, so it is light. On an older machine without supported graphics hardware the load can still be noticeable.