ExoPlayer DRM errors on Android TV: provisioning, security level and licence failures

Start with the error class, not the message

Media3 and ExoPlayer report DRM problems through dedicated error codes on PlaybackException, and the specific exception type tells you which stage failed. A DrmSessionException wrapping a MediaDrmCallbackException points at the network call to your licence server. A MediaDrmStateException points at the device DRM module itself. A provisioning error means the device could not obtain its own credentials before it could even ask for a licence.

That distinction matters because the three have entirely different fixes: one is your backend, one is the device, and one is Google's provisioning service. Logging the exception class and cause chain rather than only the user-facing message is what makes them separable in production.

Provisioning failures

Before a device can request a licence, its Widevine module must be provisioned - it fetches a device certificate from Google. This normally happens once, invisibly, but it fails on devices with no reliable internet at first launch, on devices whose system clock is wrong, and on some non-certified or heavily modified hardware.

A wrong clock is the one worth checking first, because it is common on set-top boxes that lost power, and it also breaks TLS to your own licence server - so it can present as several unrelated failures at once.

L1 versus L3: when only HD fails

If standard definition plays and HD does not, the cause is almost always Widevine security level. L1 means keys and decryption are handled inside the trusted execution environment and the device is eligible for HD and UHD. L3 is software-backed, and licence policy for premium content typically caps it to standard definition.

The security level is a property of the device and can be read from the MediaDrm instance. It is not something the app can raise - and the cap is enforced by your licence server's policy, so this is a business rule to confirm with the rights holder rather than a bug to fix in the player. Certified televisions are usually L1; inexpensive streaming boxes and emulators are frequently L3.

Licence server problems

When the failure is in the callback to your licence server, the useful information is on the server side: what the request contained, what status it returned, and whether the entitlement check passed. The common causes are consistent across projects.

• An authentication token that was valid at sign-in but expired before playback started, or one that is not refreshed for the licence request specifically.
• Entitlement genuinely denied - the account does not have rights to that title, which is the system working correctly and should be surfaced as a clear message rather than a playback error.
• Key rotation on live streams without multi-session support enabled in the player, so the session cannot acquire the new key mid-stream.
• A licence server that is reachable from your network but not from the device network, most often a certificate or DNS difference rather than a firewall.
• Offline playback attempted with a licence whose duration has expired, which fails at playback rather than at download.

Ruling DRM out entirely

The fastest way to confirm whether DRM is involved at all is to play the same asset unencrypted. If the clear version fails too, the problem is the stream, the ladder or the network, and the DRM layer is a red herring - which happens more often than it should, because a decode failure and a licence failure both surface as "the video will not play".