Troubleshooting

First confirm that the player uses the playbackUrl returned by the SDK and that the playback session is not released before playback ends. The checks below apply to the Web, Android, iOS, and Windows SDKs.

Quick triage

Symptom	Check first	Expected behavior
Playback fails	Original media URL, origin authorization, and player errors	The SDK does not replace the player's authorization or decoding path
Playback works but acceleration is absent	Key status, content identity, network policy, and eligible viewers	Playback continues when acceleration is temporarily unavailable
Peer count is zero	Application, Key, contentId, and media identity	Zero is normal when no other eligible viewer is online for the same content
No data in the console	Session lifecycle, telemetry endpoint reachability, and query range	Statistics are asynchronous and may have a short delay
Only some devices fail	Platform version, ABI, Service Worker, and network policy	Verify the runtime prerequisites for that platform first

TRACKER_UNAVAILABLE

This means that the session could not establish an acceleration connection at that time. Check, in order:

1. The SDK Key is enabled and bound to the expected application and platform in the console.
2. The application can reach the HTTPS/WSS endpoints used by the configuration and acceleration services.
3. A browser, enterprise gateway, firewall, or VPN is not blocking WebSocket traffic.
4. The media URL is still directly reachable by the player.

This does not change the normal playback path. After fixing the Key or network policy, create a new playback session to verify the change instead of repeatedly retrying the failed session.

Peer count is zero

Peers can appear only when all of these conditions are met:

• Clients use an SDK Key from the same application with compatible sharing policy;
• They play the same media and use a stable contentId;
• Other viewers are online and have requested the same content;
• Their networks allow the required connections.

Do not use a changing signed URL as the content identity. Pass a stable contentId for each actual media asset; do not include signatures, timestamps, or random parameters. A peer count of zero at startup is common. Observe again after other viewers have joined.

The playback URL has no effect

The SDK returns a playback URL after creating a session. Confirm that:

1. The player loads session.playbackUrl, rather than a previously stored original URL.
2. Application code does not reassemble, encode, or replace the returned URL.
3. Cookies, Authorization, or other origin request headers required by the player are passed through the platform API.
4. The playback URL remains valid for the full playback session; short-lived signed URLs must be refreshed according to the origin's rules.

The SDK does not create media authorization and does not send origin tokens to other viewers.

401, 403, 421, or 503

• 401 / 403: Usually an authorization failure for the media URL, Cookie, Authorization header, or origin allow-list. Verify the original URL with a controlled request outside the player.
• 421: The request reached a service center that does not match the tenant route. Check the deployment entry point, reverse proxy, and tenant routing; do not add a temporary client region field.
• 503 HOME_REGION_UNRESOLVED: The service cannot resolve the SDK Key's tenant home region. Check that the Key belongs to the current environment and that the server-side regional configuration is complete.

After fixing the service or origin configuration, close the old session and create a new one. Do not treat these responses as a player decoding error.

Playback works but the console has no statistics

Statistics are processed asynchronously through a background path; application code should not call a statistics endpoint directly. Confirm that:

• The session calls close, dispose, or the platform equivalent;
• The player does not destroy the session immediately after initialization;
• CSP, a proxy, or a firewall does not block the telemetry and configuration endpoints;
• The console query uses the correct application, Key, platform, and time range.

A short delay is expected. Do not initialize the SDK again or duplicate reports just because statistics have not appeared yet.

Old data remains after switching content

Create an independent playback session for each media asset. When switching content:

1. Stop the old player and release the old session;
2. Create a session with the new URL and stable contentId;
3. Pass the new session's playbackUrl to the player;
4. Send buffer and playback-position updates to the new session.

Do not reuse a session or contentId across unrelated media assets.

MP4, MP3, or range-request errors

Direct MP4/MP3 acceleration requires the player and origin to support a single Range request and return a valid 206 Partial Content response with Content-Range. Check that:

• The origin or CDN does not remove the Range request header;
• Content-Length, Content-Range, and the MIME type are correct;
• The Web integration registered and enabled a same-origin Service Worker as documented;
• A URL without an extension has an explicit MIME type.

When these conditions are not met, the media can still play normally, but the corresponding acceleration capability is not enabled.

Live latency or stalls

First distinguish player buffering from an acceleration connection issue:

1. Record player buffer duration, current position, and manifest refresh errors;
2. Use one stable live contentId for the live session; do not create a session per segment;
3. Check that the live manifest, segments, and authorization URLs remain valid;
4. Compare the same playback URL with P2P disabled to determine whether the issue only appears when acceleration is enabled.

Do not disable the player's own live buffering and reconnect policy solely to pursue lower latency.

Security and logs

When reporting an issue, provide the time, platform, SDK version, a redacted Key suffix, contentId, session ID, error code, and a statistics summary. Never upload a full SDK Key, origin token, Cookie, Authorization header, or personal information.

Minimum information for a support request

Time (including timezone):
Platform and OS version:
SDK version:
Application / Key (redacted):
contentId:
Media type: HLS / DASH / MP4 / MP3
Symptom: playback failure / zero peers / missing statistics / stalls / other
Error code or log (redacted):
Reproduces after changing networks: yes / no
Uses the SDK-returned playbackUrl: yes / no