Mintplex-Labs/anything-llm · error · YoutubeTranscriptError

No suitable caption track found for the video

Error message

No suitable caption track found for the video

What it means

Thrown by `YoutubeTranscript` when `#findPreferredCaptionTrack(videoBody, preferredLanguages)` returns nothing — YouTube's watch page HTML was fetched successfully, but none of the available caption tracks matched the requested language preference list. This is a content-availability error, not a network error: the video exists but has no usable captions for the requested languages.

Source

Thrown at collector/utils/extensions/YoutubeTranscript/YoutubeLoader/youtube-transcript.js:161

   * @param {string} videoId - YouTube video ID
   * @param {string[]} preferredLanguages - Array of preferred language codes
   * @returns {Promise<Object>} The preferred caption track
   * @throws {YoutubeTranscriptError} If no suitable caption track is found
   */
  static async #getPreferredCaptionTrack(videoId, preferredLanguages) {
    const videoResponse = await fetch(
      `https://www.youtube.com/watch?v=${videoId}`,
      { credentials: "omit" }
    );
    const videoBody = await videoResponse.text();

    const preferredCaptionTrack = this.#findPreferredCaptionTrack(
      videoBody,
      preferredLanguages
    );

    if (!preferredCaptionTrack) {
      throw new YoutubeTranscriptError(
        "No suitable caption track found for the video"
      );
    }

    return preferredCaptionTrack;
  }

  /**
   * Fetch transcript from YouTube video
   * @param {string} videoId - Video URL or video identifier
   * @param {Object} config - Configuration options
   * @param {string} [config.lang='en'] - Language code (e.g., 'en', 'es', 'fr')
   * @returns {Promise<string>} Video transcript text
   */
  static async fetchTranscript(videoId, config = {}) {
    const preferredLanguages = config?.lang ? [config?.lang, "en"] : ["en"];
    const identifier = this.retrieveVideoId(videoId);

View on GitHub (pinned to 526360e320)

Solutions

  1. Widen `preferredLanguages` to include the video's actual caption languages, or pass an empty/auto-include list if available.
  2. Check the video on youtube.com to confirm captions exist and in which languages.
  3. If captions demonstrably exist, suspect a parser break in `#findPreferredCaptionTrack` and patch it against the current watch-page HTML structure.
  4. Handle this as a terminal, non-retryable error — retrying will not add captions.

Example fix

// before
const transcript = await YoutubeTranscript.fetchTranscript(videoId, { lang: 'en' });

// after — fall back to auto/auto-translated tracks, then give a clear message
try {
  return await YoutubeTranscript.fetchTranscript(videoId, { lang: 'en' });
} catch (e) {
  if (/No suitable caption track/i.test(e.message)) {
    return await YoutubeTranscript.fetchTranscript(videoId, { lang: 'en', includeAuto: true });
  }
  throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check available caption languages if you expose a helper; otherwise validate language codes:
function validLangs(langs) {
  return Array.isArray(langs) && langs.every(l => /^[a-z]{2}(-[A-Za-z]{2,4})?$/.test(l)) && langs.length > 0;
}

Type guard

function isNoCaptionTrackError(e) {
  return /No suitable caption track/i.test(e?.message || '');
}

Try / catch

try {
  return await YoutubeTranscript.fetchTranscript(videoId, { lang: 'en' });
} catch (e) {
  if (!isNoCaptionTrackError(e)) throw e;
  // terminal — no retry; optionally try auto-generated tracks if supported
  return null;
}

Prevention

When it happens

Trigger: Video has captions only in languages outside `preferredLanguages` (default typically `['en']`); captions exist but are auto-generated only and the filter excludes auto tracks; the video has captions disabled by the uploader; `preferredLanguages` was passed as an empty array or with malformed codes; YouTube changed the watch-page HTML so the track list parser returns empty (parser breakage masquerading as 'no track').

Common situations: Ingesting foreign-language videos without overriding the language preference; a YouTube HTML-structure change breaks the caption-track extractor (this is exactly the 'flaky dependency' the in-house port was meant to patch); uploader disabled subtitles.

Related errors

AI-assisted analysis of Mintplex-Labs/anything-llm@526360e320 (2026-08-13). Data as JSON: /api/errors/222d1e8af71f9dc3. Report an issue: GitHub.