mozilla/pdf.js · error · Error

Please provide binary data as `Uint8Array`, rather than `Buf

Error message

Please provide binary data as `Uint8Array`, rather than `Buffer`.

What it means

Thrown only in the GENERIC build running under Node.js, when the 'data' property passed to getDocument() is a Node Buffer. Buffers are Uint8Array subclasses but their allocation semantics can break transfer to the worker thread, so PDF.js explicitly rejects them and asks for a plain Uint8Array.

Source

Thrown at src/display/api_utils.js:65

      return url;
    }
  }
  throw new Error(
    "Invalid PDF url data: " +
      "either string or URL-object is expected in the url property."
  );
}

function getDataProp(val) {
  // Converting string or array-like data to Uint8Array.
  if (
    typeof PDFJSDev !== "undefined" &&
    PDFJSDev.test("GENERIC") &&
    isNodeJS &&
    typeof Buffer !== "undefined" && // eslint-disable-line no-undef
    val instanceof Buffer // eslint-disable-line no-undef
  ) {
    throw new Error(
      "Please provide binary data as `Uint8Array`, rather than `Buffer`."
    );
  }
  if (val instanceof Uint8Array && val.byteLength === val.buffer.byteLength) {
    // Use the data as-is when it's already a Uint8Array that completely
    // "utilizes" its underlying ArrayBuffer, to prevent any possible
    // issues when transferring it to the worker-thread.
    return val;
  }
  if (typeof val === "string") {
    return stringToBytes(val);
  }
  if (
    val instanceof ArrayBuffer ||
    ArrayBuffer.isView(val) ||
    (typeof val === "object" && !isNaN(val?.length))
  ) {
    return new Uint8Array(val);

View on GitHub (pinned to 5903d58d58)

Solutions

Convert the Buffer to a Uint8Array that owns its buffer: new Uint8Array(buffer).
Read with an explicit Uint8Array target, e.g. fs.promises.readFile(path) then new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength) only when byteOffset/length align — simplest is new Uint8Array(buf).
Stream the file into a pre-allocated Uint8Array if memory is a concern.

Example fix

// before
const data = fs.readFileSync('file.pdf');
getDocument({ data });

// after
const data = new Uint8Array(fs.readFileSync('file.pdf'));
getDocument({ data });

Defensive patterns

Strategy: validation

Validate before calling

function toUint8Array(data) {
  if (typeof Buffer !== 'undefined' && data instanceof Buffer) {
    return new Uint8Array(data);
  }
  return data;
}
getDocument({ data: toUint8Array(raw) });

Type guard

const isPossiblyBuffer = (v): v is Uint8Array | ArrayBufferLike =>
  v instanceof Uint8Array || v instanceof ArrayBuffer || ArrayBuffer.isView(v);

Try / catch

null

Prevention

In Node, wrap fs.readFileSync with new Uint8Array(...) at the call site.
Never let Buffer reach pdfjs; convert at the boundary.
Add a unit test that asserts Uint8Array ownership.

When it happens

Trigger: In Node: getDocument({ data: fs.readFileSync(path) }) where readFileSync returns a Buffer; receiving a Buffer from an HTTP response and passing it directly.

Common situations: Server-side rendering, PDF processing scripts, Electron main process using Node fs; migrating from an older pdfjs version that silently accepted Buffers.

Related errors

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