mozilla/pdf.js · error · Error

The `container` must be absolutely positioned.

Error message

The `container` must be absolutely positioned.

What it means

Thrown by the PDFViewer constructor (GENERIC build only) when the container element is visible (offsetParent is truthy) but its computed CSS position is not 'absolute'. The viewer positions page views absolutely within the container and requires position:absolute for correct layout.

Source

Thrown at web/pdf_viewer.js:332

      throw new Error(
        `The API version "${version}" does not match the Viewer version "${viewerVersion}".`
      );
    }

    this.container = options.container;
    this.viewer = options.viewer || options.container.firstElementChild;
    this.#viewerAlert = options.viewerAlert || null;

    if (typeof PDFJSDev === "undefined" || PDFJSDev.test("GENERIC")) {
      if (this.container?.tagName !== "DIV" || this.viewer?.tagName !== "DIV") {
        throw new Error("Invalid `container` and/or `viewer` option.");
      }

      if (
        this.container.offsetParent &&
        getComputedStyle(this.container).position !== "absolute"
      ) {
        throw new Error("The `container` must be absolutely positioned.");
      }
    }
    this.#resizeObserver.observe(this.container);

    this.eventBus = options.eventBus;
    this.linkService = options.linkService || new SimpleLinkService();
    this.downloadManager = options.downloadManager || null;
    this.findController = options.findController || null;
    this.#altTextManager = options.altTextManager || null;
    this.#commentManager = options.commentManager || null;
    this.#signatureManager = options.signatureManager || null;
    this.#editorUndoBar = options.editorUndoBar || null;

    if (this.findController) {
      this.findController.onIsPageVisible = pageNumber =>
        this._getVisiblePages().ids.has(pageNumber);
    }
    this._scriptingManager = options.scriptingManager || null;

View on GitHub (pinned to 5903d58d58)

Solutions

1. Set the container to position:absolute (or hide it during init if dynamic).
2. Include the standard pdf_viewer.css / viewer.css which sets #viewerContainer { position: absolute; }.
3. If integrating dynamically, set container.style.position = 'absolute' before constructing PDFViewer.

Example fix

// before
<div id="viewerContainer" style="position: relative;"></div>

// after
<div id="viewerContainer" style="position: absolute; inset: 0;"></div>

const container = document.querySelector('div#viewerContainer');
if (container && getComputedStyle(container).position === 'absolute') {
  new PDFViewer({ container });
}

When it happens

Trigger: Container with position:relative/static/fixed, or default static positioning while the element is laid out (offsetParent non-null). Hidden containers (offsetParent null) are exempt.

Common situations: Custom CSS overriding the default viewer styles; integrating PDFViewer into a layout framework that sets position:relative; missing the standard pdf.css rules.

Related errors

• Invalid `container` and/or `viewer` option.
• Unknown CMap name: ${name}
• Built-in CMap parameters are not provided.
• Failed to fetch file "${url}" with "${response.statusText}".
• Image exceeded maximum allowed size and was removed.

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