Troubleshooting

This page covers common player and embedding issues. For upload, access, or account issues, start with Troubleshooting in the diagnostics section.

The video does not load or freezes

What happens. The player opens, but the video does not load or playback freezes.

Why. Network problems or background tabs often consume browser resources.

What to do.

1. Check your connection with Speedtest .
2. Close every tab except the player, then reload the page.

DRM does not work in incognito mode on Android

What happens. A Widevine-protected video does not play in incognito mode on Android.

Why. Chrome disabled Widevine in incognito mode on Android starting with version 62. This prevents users from losing paid licenses when they close tabs.

What to do. Watch DRM-protected videos in the browser’s regular mode.

Learn more in Media updates in Chrome 62 .

The screen can be recorded while protection is enabled

What happens. The screen can still be recorded while Widevine DRM is enabled.

Why. Some CSS on a parent element or the iframe can break browser capture protection.

What to do. Check these known cases:

• A parent element has border-radius. Set overflow: initial or overflow: visible.
• In Firefox on macOS, transform is applied to the player or video element, or to an ancestor with a stacking context.
• The page uses backdrop-filter or filter.
• The player <iframe> or a parent element uses aspect-ratio or padding-top.

Learn more in the Chromium issue about filter .

DRM does not work in Android WebView

What happens. A protected video does not play inside Android WebView.

Why. WebView often lacks EME or Widevine support, or the support is disabled.

What to do. Check support with the Shaka Player demo . A null value means the feature is unsupported. Configure WebView or use the system browser.

Learn more in video.js #5563 , Widevine in Android WebView , and protected content in WebView .

DRM does not work in Electron

What happens. Widevine-protected video does not play in an Electron app.

Why. You must connect and test the CDM in Electron separately from regular Chrome.

What to do. Follow Electron’s guide for testing the Widevine CDM.

Learn more in Testing Widevine CDM .

play() does not start from a custom button

What happens. A user clicks your button and you call the play() API, but playback does not start.

Why. The browser recognizes the gesture only when it reaches the media element or player. This is part of the autoplay policy .

What to do. Make sure the user clicks the player. Set pointer-events: none on your overlays so the click passes through them.

NotAllowedError occurs

What happens. The console or API response contains NotAllowedError with a message such as “The request is not allowed by the user agent …” or “The request is not triggered by a user activation.”

Why. A browser API requires user interaction or must run as a direct result of a click or tap.

What to do. Call the method directly from the user’s click or tap handler. Do not move it into a deferred chain outside the user gesture.

Learn more about User activation on MDN.

Autoplay does not work in Electron

What happens. Video autoplay does not start in Electron.

Why. Electron has its own media autoplay restrictions, which differ from regular browsers.

What to do. Check autoplay policies in the window and webPreferences settings. Review the workarounds in the discussions below.

Learn more in MMM-ISS-Live #1 and cordova-electron #102 .

A page with many players freezes

What happens. A page contains many embedded players, and the tab slows down or freezes.

Why. Each player uses resources. Without lazy loading, the load grows with every player.

What to do. Use the techniques in Optimization .

Fullscreen does not work in a nested iframe

What happens. Fullscreen mode does not start when the player is inside an iframe nested in another iframe.

Why. The allow attribute may not work correctly if the parent <iframe> is not populated through src, for example when using a form target or writing content directly.

What to do. Remove allow from the player <iframe> and keep only allowfullscreen. On iOS, also see Pseudo-fullscreen mode .

The screen does not rotate in a PWA

What happens. The screen does not rotate while the player is in fullscreen mode in a PWA.

Why. The app orientation is fixed in manifest.json.

What to do. Remove the orientation property from manifest.json. Then listen for fullscreen changes and control the orientation lock:

player.on(player.Events.FullscreenChange, (event) => {
  if (event.data.isFullscreen) {
    screen.orientation.unlock()
  } else {
    screen.orientation.lock('portrait')
  }
})

Next steps

• Supported platforms
• Support chat