angular/components · error · Error

Namespace YT not found, cannot construct embedded youtube pl

Error message

Namespace YT not found, cannot construct embedded youtube player. Please install the YouTube Player API Reference for iframe Embeds: https://developers.google.com/youtube/iframe_api_reference

What it means

The Angular Components YouTube player wrapper requires the external YouTube IFrame Player API script, which defines the global window.YT namespace. In dev mode, if window.YT is missing (or YT.Player is not a function) when the component tries to load, and the component is not configured to fetch the API itself, it throws this error telling you to install the YouTube IFrame API.

Source

Thrown at src/youtube-player/youtube-player.ts:508

   */
  protected _load(playVideo: boolean) {
    // Don't do anything if we're not in a browser environment.
    if (!this._isBrowser) {
      return;
    }

    // Might be clobbered by something like `<form id="YT"><input name="Player"></form>`.
    if (
      typeof window.YT !== 'object' ||
      !window.YT ||
      !window.YT.Player ||
      typeof window.YT.Player !== 'function'
    ) {
      if (this.loadApi) {
        this._isLoading = true;
        loadApi(this._nonce);
      } else if (this.showBeforeIframeApiLoads && (typeof ngDevMode === 'undefined' || ngDevMode)) {
        throw new Error(
          'Namespace YT not found, cannot construct embedded youtube player. ' +
            'Please install the YouTube Player API Reference for iframe Embeds: ' +
            'https://developers.google.com/youtube/iframe_api_reference',
        );
      }

      const existingCallback = (window as YoutubeWindow).onYouTubeIframeAPIReady;

      // The callback might be clobbered by an element with an ID of `onYouTubeIframeAPIReady`.
      if (typeof existingCallback === 'function') {
        this._existingApiReadyCallback = (window as YoutubeWindow).onYouTubeIframeAPIReady;
      }

      (window as YoutubeWindow).onYouTubeIframeAPIReady = () => {
        this._existingApiReadyCallback?.();
        this._ngZone.run(() => this._createPlayer(playVideo));
      };
    } else {

View on GitHub (pinned to 0411926e7d)

Solutions

1. Set the loadApi input to true so the component loads the YouTube IFrame API script itself: <youtube-player loadApi>
2. If loading the API manually, add <script src="https://www.youtube.com/iframe_api"></script> to index.html and wait for window.onYouTubeIframeAPIReady before rendering/playing
3. Check that CSP or ad blockers aren't blocking scripts from youtube.com; whitelist them
4. Avoid calling playVideo() before the YT namespace is available (wait for the player's ready event)

Example fix

// before
<youtube-player videoId="dQw4w9WgXcQ" [loadApi]="false"></youtube-player>
// after
<youtube-player videoId="dQw4w9WgXcQ" [loadApi]="true"></youtube-player>

function isYouTubeApiReady(): boolean {
  return typeof window !== 'undefined' && !!(window as any).YT && typeof (window as any).YT.Player === 'function';
}
if (!isYouTubeApiReady()) console.warn('YT API not loaded yet; defer playVideo()');

function hasYouTubeNamespace(w: Window): w is Window & { YT: { Player: Function } } {
  return 'YT' in w && typeof (w as any).YT?.Player === 'function';
}

try {
  player.playVideo();
} catch (e) {
  if (String(e?.message).includes('Namespace YT not found')) {
    loadIframeApi().then(() => player.playVideo());
  } else { throw e; }
}

When it happens

Trigger: A YouTubePlayer is instantiated and _load runs (via playVideo() or _conditionallyLoad) before window.YT exists, with loadApi=false so the component does not call loadApi(), and showBeforeIframeApiLoads=true causing the throw in ngDevMode.

Common situations: Forgetting to include https://www.youtube.com/iframe_api in index.html or loadIframeApi API; loading the app inside an environment where the YouTube script is blocked (ad blockers, CSP) or slow; setting [loadApi]="false" without manually loading the API; calling playVideo() before the API finishes loading.

Related errors

• MarkerClusterer class not found, cannot construct a marker c
• Namespace google not found, cannot construct embedded google
• Maps event target that uses native events must have `addEven
• Unsupported MatButton appearance "${appearance}"
• A mat-tab-nav-panel must be specified via [tabPanel].

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/dc4ab8105510bb59. Report an issue: GitHub.