Lesson 9 of 10

Flex SDK Troubleshooting

Same support fundamentals — HTTP, auth, events — running inside a richer state machine: workers, tasks, and reservations that can each fail independently.

What the SDK owns

@twilio/flex-sdk gives a custom app the same building blocks the stock Flex UI is built on.

Worker (WK…)

The agent's identity in TaskRouter — activity state (Available, Reserved, WrapUp), attributes, skills.

Task (WT…)

A unit of work waiting to be routed — a call, a chat, an email. Carries attributes a Workflow uses to route it.

Reservation (WR…)

One worker's offer to handle one task. Its status — pending, accepted, rejected, timeout, canceled — is where most "agent can't accept" bugs actually live.

Conversation

The Conversations-SDK-backed thread behind a chat/email task — participants, transcript, and its own independent lifecycle from the task that spawned it.

Voice client

The embedded Voice SDK connection carrying call audio and controls — a task can be "accepted" in TaskRouter while this is still silently broken.

Where it breaks: five real failure modes

Each of these looks like a different bug from the outside — knowing which layer owns it is most of the diagnosis.

AcceptTask drops call context

For voice tasks, you must register a VoiceClientEvent listener before calling AcceptTask. Skip it and acceptance can succeed while the agent gets no audio or call controls.

Worker stuck in Reserved or WrapUp

The reservation only clears when the client actually calls CompleteTask (and WrapUpTask, if wrap-up is configured). A call that errors silently — or never fires — parks the worker indefinitely.

Token refresh failure

Error 45775 — the refresh token is malformed, expired, or clock-skewed. Fixing validateToken/refreshToken locally isn't enough: the session stays stale until the client actually calls client.updateToken with the new pair.

Degraded SDK client

If TaskRouter, Conversations, Voice, or Sync fails to initialize, Flex loads anyway in a reduced-capability "degraded" state. A degraded Voice client next to a healthy TaskRouter client reads like a routing bug, not a connectivity one.

Conversations task orphaning

Several distinct causes, not one bug: a declined Interaction invite cancels the task but leaves the conversation open; inviting a participant already in another open conversation fails silently; an unhandled workflow.timeout/task.canceled/task.deleted leaves nothing tracking the conversation at all.

Exercises

Read the sanitized reservation payload and console excerpt below, then work through both exercises.

{
  "reservation": {
    "sid": "WRxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "worker_sid": "WKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "task_sid": "WTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "reservation_status": "wrapping",
    "date_created": "2026-07-29T18:02:11Z",
    "date_updated": "2026-07-29T18:14:47Z"
  },
  "worker": {
    "activity_sid": "WAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "activity_name": "WrapUp",
    "available": false
  }
}

16:14:03 | log   | SessionState: setting degraded to false
16:14:47 | warn  | AcceptTask resolved but no VoiceClientEvent listener was registered
16:14:52 | error | 45775: Failed to refresh token. Invalid token provided.

Concept check

Answer in your head first, then click a question to reveal the answer.

Scenario checklist

A worker is stuck in WrapUp after a call ended. Work the checklist and check each item off. Progress is saved in your browser.

Check the reservation's status (pending/accepted/wrapping/timeout) before assuming it's a routing bugConfirm the client actually called CompleteTask / WrapUpTask, not just that the UI looks idleFor voice tasks, confirm a VoiceClientEvent listener was registered before AcceptTaskScan the session log for "setting degraded to true" and identify which underlying client failedIf auth-related, confirm updateToken was actually called after the backend issued a new token

Go deeper

These primers are a starting point. Read the primary sources to build real fluency.

Twilio Docs: Flex SDK methodsThe full method reference — AcceptTask, CompleteTask, updateToken, and the rest Twilio Docs: Flex SDK authenticationLogin details, token exchange, and the client lifecycle end to end Twilio Docs: Error 45775Failed to refresh token — causes and the correct updateToken recovery path Twilio Docs: Flex Conversations best practicesThe specific patterns (close timers, known-agent routing) that prevent orphaned conversations

Training Notes

What building this project taught me.

This builds on Events and SSO edge cases, not repeats them

Events covers webhooks/retries/idempotency in the abstract; SSO & Identity Edge Cases covers enterprise federation. This lesson is where both show up inside one stateful client SDK — a reservation is basically an event you have to act on, and a Flex token refresh is SSO's token-exchange problem with a shorter clock.

Grounded in live Twilio docs, not invented

The failure modes here — error 45775, the VoiceClientEvent listener requirement, the three distinct Conversations-orphaning causes — came from the twilio-docs MCP, the same sourcing discipline the Support Triage Assistant's grounding packs use.