mozilla/pdf.js · error · Error

Invalid spread mode: ${mode}

Error message

Invalid spread mode: ${mode}

What it means

Thrown by PDFViewer.spreadMode setter when mode fails isValidSpreadMode: must be an integer in SpreadMode enum excluding UNKNOWN. Valid values are SpreadMode.NONE(0), ODD(1), EVEN(2).

Source

Thrown at web/pdf_viewer.js:2382

   * @param {number} mode - Group the pages in spreads, starting with odd- or
   *   even-number pages (unless `SpreadMode.NONE` is used).
   *   The constants from {SpreadMode} should be used.
   */
  set spreadMode(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._spreadMode === mode) {
      return; // The Spread mode didn't change.
    }
    if (!isValidSpreadMode(mode)) {
      throw new Error(`Invalid spread mode: ${mode}`);
    }
    this.clearSelection();
    this._spreadMode = mode;
    this.eventBus.dispatch("spreadmodechanged", { source: this, mode });

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

  _updateSpreadMode(pageNumber = null) {
    if (!this.pdfDocument) {
      return;
    }
    const viewer = this.viewer,
      pages = this._pages;

    if (this._scrollMode === ScrollMode.PAGE) {
      this.#ensurePageViewVisible();
    } else {

View on GitHub (pinned to 5903d58d58)

Solutions

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

Example fix

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

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

const valid = Object.values(SpreadMode).includes(mode) && mode !== SpreadMode.UNKNOWN;
if (Number.isInteger(mode) && valid) {
  viewer.spreadMode = mode;
} else {
  viewer.spreadMode = SpreadMode.NONE;
}

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

When it happens

Trigger: Setting viewer.spreadMode = 3, -1 (UNKNOWN), NaN, or a non-integer. From a corrupted persisted preference or out-of-range toolbar value.

Common situations: Saved spread-mode preference from a future/older version with different enum numbering; custom control indexing incorrectly; NaN from failed parse.

Related errors

• Invalid scroll 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/b225acd33761723d. Report an issue: GitHub.