videojs/video.js · error · Error

TextTrack kind is required but was not provided

Error message

TextTrack kind is required but was not provided

What it means

Thrown by Tech#addTextTrack(kind, label, language) when the first positional argument is falsy. The HTML5 TextTrack spec requires a 'kind', and video.js enforces it synchronously before delegating to createTrackHelper. Valid kinds are 'subtitles', 'captions', 'descriptions', 'chapters', and 'metadata'.

Source

Thrown at src/js/tech/tech.js:724

  /**
   * Create and returns a remote {@link TextTrack} object.
   *
   * @param {string} kind
   *        `TextTrack` kind (subtitles, captions, descriptions, chapters, or metadata)
   *
   * @param {string} [label]
   *        Label to identify the text track
   *
   * @param {string} [language]
   *        Two letter language abbreviation
   *
   * @return {TextTrack}
   *         The TextTrack that gets created.
   */
  addTextTrack(kind, label, language) {
    if (!kind) {
      throw new Error('TextTrack kind is required but was not provided');
    }

    return createTrackHelper(this, kind, label, language);
  }

  /**
   * Create an emulated TextTrack for use by addRemoteTextTrack
   *
   * This is intended to be overridden by classes that inherit from
   * Tech in order to create native or custom TextTracks.
   *
   * @param {Object} options
   *        The object should contain the options to initialize the TextTrack with.
   *
   * @param {string} [options.kind]
   *        `TextTrack` kind (subtitles, captions, descriptions, chapters, or metadata).
   *
   * @param {string} [options.label].

View on GitHub (pinned to c3a7e0e6d2)

Solutions

1. Pass a valid kind string as the first argument: 'subtitles', 'captions', 'descriptions', 'chapters', or 'metadata'.
2. Validate the config value is one of the five valid kinds before calling addTextTrack.
3. If kind is optional in your UI, default it to 'subtitles' explicitly.

Example fix

// before
player.addTextTrack(undefined, 'English', 'en');
// after
player.addTextTrack('subtitles', 'English', 'en');

const VALID_KINDS = ['subtitles', 'captions', 'descriptions', 'chapters', 'metadata'];
function addTrackSafe(player, kind, label, language) {
  if (!VALID_KINDS.includes(kind)) {
    throw new TypeError(`kind must be one of ${VALID_KINDS.join(', ')}, got: ${kind}`);
  }
  return player.addTextTrack(kind, label, language);
}

function isTextTrackKind(kind) {
  return typeof kind === 'string' && ['subtitles','captions','descriptions','chapters','metadata'].includes(kind);
}

try {
  player.addTextTrack(kind, label, language);
} catch (err) {
  if (/TextTrack kind is required/.test(err.message)) {
    player.addTextTrack('subtitles', label, language);
  } else { throw err; }
}

When it happens

Trigger: Calling player.addTextTrack() / tech.addTextTrack() with no arguments, with undefined, null, or an empty string as the first argument. Also when a config-driven caller passes label as the first argument by positional confusion (e.g. addTextTrack('English','en')).

Common situations: Building subtitle/caption menus dynamically where 'kind' comes from user config or a data file that may omit it; refactoring a label-first API into the kind-first video.js API; SSR builds where the track list is constructed before kind is resolved.

Related errors

• Invalid color code provided, ' + color + '; must be formatte
• A tech was not provided.
• class has illegal whitespace characters
• currentDimension only accepts width or height value
• Illegal component name, "${name}"; must be a non-empty strin

AI-assisted analysis of videojs/video.js@c3a7e0e6d2 (2026-08-13). Data as JSON: /api/errors/635f9b215dba1189. Report an issue: GitHub.