mozilla/pdf.js · error · Error

Invalid PDF url data: either string or URL-object is expecte

Error message

Invalid PDF url data: either string or URL-object is expected in the url property.

What it means

Thrown by getUrlProp while normalizing the 'url' field passed to getDocument(). The function accepts only a URL instance or a string; in browsers the string is parsed with URL.parse(val, window.location) and a null result means the value is not a valid absolute or resolvable URL. Anything else (object, number, null) reaches the throw unconditionally.

Source

Thrown at src/display/api_utils.js:50

      typeof PDFJSDev !== "undefined" &&
      PDFJSDev.test("GENERIC") &&
      isNodeJS
    ) {
      if (/^[a-z][a-z0-9\-+.]+:/i.test(val)) {
        return new URL(val);
      }
      // eslint-disable-next-line no-undef
      const url = process.getBuiltinModule("url");
      return new URL(url.pathToFileURL(val));
    }

    // The full path is required in the 'url' field.
    const url = URL.parse(val, window.location);
    if (url) {
      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`."
    );
  }

View on GitHub (pinned to 5903d58d58)

Solutions

1. Pass url as a string (absolute URL) or a URL object: getDocument({ url: new URL(string) }).
2. For binary content, pass { data: Uint8Array } instead of { url }.
3. If you only have an href, wrap it: new URL(href, window.location.href).

Example fix

// before
getDocument({ url: someLocationObject });

// after
getDocument({ url: new URL(someLocationObject.href) });
// or
getDocument({ url: 'https://example.com/file.pdf' });

function normalizeUrl(u) {
  if (u instanceof URL) return u;
  if (typeof u === 'string') {
    try { return new URL(u, typeof location !== 'undefined' ? location.href : undefined); }
    catch { return null; }
  }
  return null;
}
const url = normalizeUrl(source);
if (!url) throw new Error('source must be a URL or URL string');
getDocument({ url });

const isUrlInput = (v): v is string | URL =>
  typeof v === 'string' || v instanceof URL;

try {
  loadingTask = getDocument({ url });
} catch (e) {
  if (e.message.startsWith('Invalid PDF url data')) { /* fix source */ }
  else throw e;
}

When it happens

Trigger: getDocument({ url: 123 }), getDocument({ url: { href: '...' } }), getDocument({ url: null }), or a malformed string that URL.parse rejects. Also triggered when 'url' and 'data' are both omitted is a different path, but a non-URL-shaped url hits this.

Common situations: Passing a Location or Anchor object instead of URL/string; relative URL in a non-browser env without window.location; typos in field names leaving url as undefined-then-coerced; Cypress/jsdom where window.location is unusual.

Related errors

• getDocument - expected either `data`, `range`, or `url` para
• Invalid PDF binary data: either TypedArray, string, or array
• A valid "url" parameter must provided.
• BinaryCMapReader.process: Invalid dataSize.
• Page count in top-level pages dictionary is not an integer.

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