Embedding youtube video "Refused to display document because display forbidden by X-Frame-Options"

Embedding youtube video "Refused to display document because display forbidden by X-Frame-Options"

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Embedding YouTube Videos and Understanding X-Frame-Options

When attempting to embed a YouTube video using an <iframe>, developers often encounter a specific security error: "Refused to display document because of the display is forbidden by X-Frame-Options." This error appears in browsers like Chrome, Firefox, and Internet Explorer when the parent page tries to load content from a domain that has explicitly disabled framing.

The issue stems from the X-Frame-Options HTTP response header sent by YouTube. When you inspect the network request for a standard YouTube URL or an embed link, you will find headers that restrict where the video can be displayed. Common values include:

  • DENY: The resource cannot be displayed in a frame at all.
  • SAMEORIGIN: The resource can only be framed by pages on the same origin.

YouTube sets this header to prevent clickjacking attacks, ensuring that their video player cannot be embedded in arbitrary websites without permission. However, this creates a conflict for developers who want to dynamically inject video content into their own applications or third-party portals.

Why Custom Headers Don't Work

A frequent misconception is that adding headers like header('X-Frame-Options: Allow-From http://www.youtube.com'); on the server hosting your page will resolve the issue. This approach fails because the restriction originates from YouTube, not your server. The browser enforces the policy based on the response received from the external domain (YouTube) when it attempts to load the iframe content. Modifying headers on your own server does not alter the X-Frame-Options header sent by YouTube's servers.

Additionally, attempting to modify the URL with parameters like &output=embed alone is insufficient if the underlying security policy forbids framing entirely. While the &output=embed parameter changes the HTML output from a standard watch page to an embed-ready iframe, it does not override the security headers controlling where that iframe can appear.

The Solution: Using YouTube's Official Embed URL

To bypass this restriction, you must use YouTube's dedicated embed endpoint rather than the standard watch URL. The standard URL format (http://www.youtube.com/watch?v=VIDEO_ID) often returns a page designed for direct browsing, which carries strict framing policies.

The correct approach is to construct an iframe source using the /embed/ path:

<iframe width="560" height="315" 
    src="https://www.youtube.com/embed/YOUR_VIDEO_ID?autoplay=1&rel=0" 
    frameborder="0" 
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
    allowfullscreen>
</iframe>

Note the following implementation details:

  1. Base URL: Replace http://www.youtube.com/watch?v= with https://www.youtube.com/embed/.
  2. Protocol: Always use https for modern implementations to ensure compatibility with browsers that have deprecated insecure content.
  3. Parameters: The /embed/ path typically responds with a header of X-Frame-Options: SAMEORIGIN. While this still technically restricts embedding from cross-origin sites, YouTube's implementation often relaxes this behavior specifically for the embed player when accessed via this URL structure compared to the standard watch page.

However, if you require the video to be embedded in an environment where SAMEORIGIN is enforced strictly (such as certain corporate intranets or specific legacy browser configurations), a more robust solution involves using YouTube's IFrame API or utilizing their Partner Program features which provide specific whitelisting options for your domain.

LaravelContext and Dynamic Embedding

If you are building an application where users submit video IDs dynamically, such as in a content management system or a social dashboard, you cannot rely solely on static HTML. You must ensure the logic generating the iframe source string correctly formats the URL using the /embed/ pattern.

In PHP-based frameworks like Laravel, this often looks like:

$videoId = request('video_id');
$url = "https://www.youtube.com/embed/{$videoId}?rel=0&modestbranding=1";

return view('layouts.app', [
    'embedUrl' => $url
]);

This ensures that even if the user provides a standard watch?v= link, your application internally converts it to the embed-compatible format before rendering the iframe. This pattern is widely adopted in video aggregation services and remains the most reliable method for cross-origin embedding without requiring server-side proxying or complex CORS configurations on YouTube's side.

Conclusion

The error "Refused to display document because of the display is forbidden by X-Frame-Options" is a direct result of browser security policies protecting users from unauthorized framing. The resolution lies not in modifying your server's response headers, but in ensuring the external resource (YouTube) is requested via its specific embed endpoint. By switching from the standard watch URL to the embed URL and adhering to the correct parameter structure, you can successfully display YouTube videos across Firefox, Chrome, and Internet Explorer without triggering security blocks.

Our network