sampotts/plyr · error · Error

Missing previewThumbnails.src config attribute

Error message

Missing previewThumbnails.src config attribute

What it means

Plyr's preview-thumbnails plugin needs at least one source of thumbnail data to do its job. getThumbnails() destructures config.previewThumbnails.src and, when is.empty(src) is true, throws before any network request is attempted. The throw occurs inside a Promise executor (new Promise((resolve) => {...})), so the Promise constructor converts it into a rejection of getThumbnails() — it surfaces as an unhandled rejection or via .catch() on the call site.

Source

Thrown at src/js/plugins/preview-thumbnails.js:141

      this.render();

      // Check to see if thumb container size was specified manually in CSS
      this.determineContainerAutoSizing();

      // Set up listeners
      this.listeners();

      this.loaded = true;
    });
  };

  // Download VTT files and parse them
  getThumbnails = () => {
    return new Promise((resolve) => {
      const { src } = this.player.config.previewThumbnails;

      if (is.empty(src)) {
        throw new Error('Missing previewThumbnails.src config attribute');
      }

      // Resolve promise
      const sortAndResolve = () => {
        // Sort smallest to biggest (e.g., [120p, 480p, 1080p])
        this.thumbnails.sort((x, y) => x.height - y.height);

        this.player.debug.log('Preview thumbnails', this.thumbnails);

        resolve();
      };

      // Via callback()
      if (is.function(src)) {
        src((thumbnails) => {
          this.thumbnails = thumbnails;
          sortAndResolve();
        });

View on GitHub (pinned to 6520022413)

Solutions

1. Set previewThumbnails.src to a valid value: a VTT URL string, an array of VTT URLs (sorted by quality), or a function(thumbnails=>{...}) that returns thumbnail objects.
2. If you do not want thumbnails, remove the previewThumbnails key entirely or set previewThumbnails.enabled = false so the plugin never instantiates.
3. Double-check the key name is exactly 'src' and that it sits directly under previewThumbnails (not nested or renamed).
4. If generating thumbnails at runtime, pass src as a function so you control when thumbnails resolve.

Example fix

// before
const player = new Plyr('#video', {
  previewThumbnails: { enabled: true }
});

// after
const player = new Plyr('#video', {
  previewThumbnails: { enabled: true, src: '/thumbnails.vtt' }
});

// Run before constructing the Plyr player
function validatePreviewThumbnails(config) {
  const pt = config && config.previewThumbnails;
  if (!pt || pt.enabled === false) return; // plugin disabled, nothing to check
  const { src } = pt;
  const ok =
    typeof src === 'function' ||
    (typeof src === 'string' && src.trim().length > 0) ||
    (Array.isArray(src) && src.length > 0 && src.every(s => typeof s === 'string' && s.trim().length > 0));
  if (!ok) {
    throw new Error('previewThumbnails is enabled but src is missing/empty. Set previewThumbnails.src to a VTT url, an array of urls, or a function.');
  }
}

validatePreviewThumbnails(playerConfig);
const player = new Plyr('#video', playerConfig);

// Type guard narrowing to an accepted src shape
function isValidPreviewThumbnailsSrc(src) {
  return (
    typeof src === 'function' ||
    typeof src === 'string' ||
    (Array.isArray(src) && src.every(s => typeof s === 'string'))
  );
}

if (config.previewThumbnails && config.previewThumbnails.enabled !== false) {
  if (!isValidPreviewThumbnailsSrc(config.previewThumbnails.src)) {
    config.previewThumbnails.enabled = false;
  }
}

// getThumbnails()'s executor converts the throw into a rejection.
// Chain .catch() wherever the plugin initializes (or wrap player.load) so a bad
// config degrades gracefully instead of producing an unhandled rejection.
try {
  // player setup that triggers thumbnail loading
} catch (e) {
  if (/Missing previewThumbnails.src/.test(e.message)) {
    console.warn('Preview thumbnails disabled:', e.message);
  } else {
    throw e;
  }
}

When it happens

Trigger: The player is constructed with the previewThumbnails plugin loaded/enabled but config.previewThumbnails.src is omitted, null, undefined, an empty string, or an empty array. Also triggered when the whole previewThumbnails object is absent but the plugin is still instantiated, or when src is supplied under the wrong key (e.g. previewThumbnails.url).

Common situations: Enabling the plugin via enabled:true but forgetting the src field; copy-paste config from an older version where the key was named differently; conditional config that yields src: undefined in a specific build/environment; renaming the VTT endpoint variable and leaving src pointing at an empty value; disabling thumbnails by setting src to '' instead of setting enabled:false.

AI-assisted analysis of sampotts/plyr@6520022413 (2026-08-13). Data as JSON: /api/errors/084ea0907b05e04d. Report an issue: GitHub.