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-Policyheader set tono-referrerorsame-origin. Some frameworks and security setups add one by default; in Willison’s case it was Django’sSecurityMiddleware, which sendssame-origin. - A meta tag in the page head:
<meta name="referrer" content="no-referrer">. - A
referrerpolicyattribute on the iframe itself, sometimes added by an embed plugin. -
noreferreron 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
baseUrlparameter, which sets theReferer. - iOS
SFSafariViewController: it cannot set aReferer, so set theoriginplayer parameter instead. - Desktop apps: add the
Refereras 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
- YouTube API Services: Required Minimum Functionality (Google for Developers).
- Error 153 Video player configuration error on YouTube embeds (Simon Willison).
- Referrer-Policy (MDN).