mozilla/pdf.js · error · Error

Invalid scroll mode: ${mode}

Error message

Invalid scroll mode: ${mode}

What it means

Thrown by PDFViewer.scrollMode setter when mode fails isValidScrollMode: must be an integer in ScrollMode enum excluding UNKNOWN. Valid values are ScrollMode.VERTICAL(0), HORIZONTAL(1), WRAPPED(2), PAGE(3).

Source

Thrown at web/pdf_viewer.js:2311

   * @param {number} mode - The direction in which the document pages should be
   *   laid out within the scrolling container.
   *   The constants from {ScrollMode} should be used.
   */
  set scrollMode(mode) {
    if (
      typeof PDFJSDev === "undefined"
        ? window.isGECKOVIEW
        : PDFJSDev.test("GECKOVIEW")
    ) {
      // NOTE: Always ignore the pageLayout in GeckoView since there's
      // no UI available to change Scroll/Spread modes for the user.
      return;
    }
    if (this._scrollMode === mode) {
      return; // The Scroll mode didn't change.
    }
    if (!isValidScrollMode(mode)) {
      throw new Error(`Invalid scroll mode: ${mode}`);
    }
    if (this.pagesCount > PagesCountLimit.FORCE_SCROLL_MODE_PAGE) {
      return; // Disabled for performance reasons.
    }
    this._previousScrollMode = this._scrollMode;

    this.clearSelection();
    this._scrollMode = mode;
    this.eventBus.dispatch("scrollmodechanged", { source: this, mode });

    this._updateScrollMode(/* pageNumber = */ this._currentPageNumber);
  }

  _updateScrollMode(pageNumber = null) {
    const scrollMode = this._scrollMode,
      viewer = this.viewer;

    viewer.classList.toggle(

View on GitHub (pinned to 5903d58d58)

Solutions

1. Use the ScrollMode enum constants instead of magic numbers.
2. Validate against Object.values(ScrollMode) excluding UNKNOWN before assigning.
3. Default to ScrollMode.VERTICAL when input is invalid.

Example fix

// before
viewer.scrollMode = Number(savedPref);

// after
import { ScrollMode } from 'pdfjs-dist/web/ui_utils.js';
const mode = Number(savedPref);
const valid = Object.values(ScrollMode).includes(mode) && mode !== ScrollMode.UNKNOWN;
viewer.scrollMode = valid ? mode : ScrollMode.VERTICAL;

const valid = Object.values(ScrollMode).includes(mode) && mode !== ScrollMode.UNKNOWN;
if (Number.isInteger(mode) && valid) {
  viewer.scrollMode = mode;
} else {
  viewer.scrollMode = ScrollMode.VERTICAL;
}

function isValidScrollMode(mode) {
  return Number.isInteger(mode) && Object.values(ScrollMode).includes(mode) && mode !== ScrollMode.UNKNOWN;
}

When it happens

Trigger: Setting viewer.scrollMode = 5, -1 (UNKNOWN), NaN, or a non-integer. Also from a corrupted persisted preference or a UI control returning an out-of-range value.

Common situations: Deserializing a saved scroll-mode preference that no longer maps to a valid enum; custom toolbar sending arbitrary indices; enum renumbering across versions.

Related errors

• Invalid spread mode: ${mode}
• Invalid page number.
• Invalid numeric scale.
• Invalid pages rotation angle.
• Invalid optionalContentConfigPromise: ${promise}

AI-assisted analysis of mozilla/pdf.js@5903d58d58 (2026-08-13). Data as JSON: /api/errors/8b091aead77f127e. Report an issue: GitHub.