YouTube embed error 153: why it happens and how to fix it

Error 153 means the YouTube player cannot tell which site embedded it, because the Referer header is missing. The fix for websites, WebViews and desktop apps.

You embed a YouTube video, the player loads, and instead of the video you get a black box that says “Error 153. Video player configuration error”, often with a “Watch on YouTube” link. The video is fine and the embed code is fine. What is missing is information about who is embedding it.

The cause: the player cannot tell which site embedded it

YouTube’s developer terms are explicit. Its Required Minimum Functionality page says that anything using the embedded player, including the IFrame Player API, must identify itself through the HTTP Referer header. Browsers normally send it on their own; the page asks you not to use settings that suppress it and recommends the strict-origin-when-cross-origin referrer policy.

When the player loads with no Referer, or with one that does not identify a site, it refuses to play and shows error 153. Developers who have debugged it, like Simon Willison, traced it to exactly that. Google’s page does not mention the number 153 itself, but the fix it describes is the one that makes the error go away.

What strips the Referer on a website

  • A Referrer-Policy header set to no-referrer or same-origin. Some frameworks and security setups add one by default; in Willison’s case it was Django’s SecurityMiddleware, which sends same-origin.
  • A meta tag in the page head: <meta name="referrer" content="no-referrer">.
  • A referrerpolicy attribute on the iframe itself, sometimes added by an embed plugin.
  • noreferrer on a window you open to host the player, which YouTube’s page tells you not to use.

The fix on a website

Send the policy YouTube recommends, as a header:

Referrer-Policy: strict-origin-when-cross-origin

or as a meta tag, if you cannot change headers:

<meta name="referrer" content="strict-origin-when-cross-origin">

Then check that nothing more specific overrides it: remove a referrerpolicy attribute from the iframe, or set it to the same value. That policy sends only your origin (for example https://example.com) to other sites, never the full path, so you do not give up meaningful privacy. Willison also found that switching the embed to youtube-nocookie.com helped only some of the time; fixing the policy is what solved it.

The fix inside an app (WebView, Electron, Tauri)

Apps hit this more often, because their pages do not come from a website. A page loaded from a local file or a custom scheme (file://, app://, tauri://localhost) has no web origin to send, so the player gets no usable Referer. YouTube’s page lists what to do per platform:

  • Mobile WebView loading local HTML: set the baseUrl parameter, which sets the Referer.
  • iOS SFSafariViewController: it cannot set a Referer, so set the origin player parameter instead.
  • Desktop apps: add the Referer as an HTTP header on the request, or configure the WebView so it sends one.

A last option, when you cannot control the WebView’s headers: host a tiny page on a real https domain you own that embeds the player, and frame that page from your app. The player then sees your domain as the embedder.

How we ran into it

We make Webstarted Toolbox, a menu bar app built with Tauri, and its Media widget plays YouTube videos. Its interface runs on tauri://localhost, which is not a valid web origin, so a direct youtube.com/embed iframe failed with error 153 every time. We fixed it with the last option above: the widget frames a small page we host on our own https domain, which sends a proper Referer and embeds the player. The video itself still streams straight from Google to the viewer; only that small page touches our server.

If you are just trying to watch the video

The error is on the site or app that embedded the video, not on your side. The “Watch on YouTube” link plays it on youtube.com. One exception worth checking: a browser extension or privacy setting that strips the Referer from every request removes the same header, and can cause error 153 on sites that are configured correctly.

Sources