{"record":{"id":"6d489daa826f2696","repo":"mozilla/pdf.js","slug":"invalid-pdf-url-data-either-string-or-url-object","errorCode":null,"errorMessage":"Invalid PDF url data: either string or URL-object is expected in the url property.","messagePattern":"Invalid PDF url data: either string or URL-object is expected in the url property\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/display/api_utils.js","lineNumber":50,"sourceCode":"      typeof PDFJSDev !== \"undefined\" &&\n      PDFJSDev.test(\"GENERIC\") &&\n      isNodeJS\n    ) {\n      if (/^[a-z][a-z0-9\\-+.]+:/i.test(val)) {\n        return new URL(val);\n      }\n      // eslint-disable-next-line no-undef\n      const url = process.getBuiltinModule(\"url\");\n      return new URL(url.pathToFileURL(val));\n    }\n\n    // The full path is required in the 'url' field.\n    const url = URL.parse(val, window.location);\n    if (url) {\n      return url;\n    }\n  }\n  throw new Error(\n    \"Invalid PDF url data: \" +\n      \"either string or URL-object is expected in the url property.\"\n  );\n}\n\nfunction getDataProp(val) {\n  // Converting string or array-like data to Uint8Array.\n  if (\n    typeof PDFJSDev !== \"undefined\" &&\n    PDFJSDev.test(\"GENERIC\") &&\n    isNodeJS &&\n    typeof Buffer !== \"undefined\" && // eslint-disable-line no-undef\n    val instanceof Buffer // eslint-disable-line no-undef\n  ) {\n    throw new Error(\n      \"Please provide binary data as `Uint8Array`, rather than `Buffer`.\"\n    );\n  }","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/src/display/api_utils.js#L32-L68","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass url as a string (absolute URL) or a URL object: getDocument({ url: new URL(string) }).","For binary content, pass { data: Uint8Array } instead of { url }.","If you only have an href, wrap it: new URL(href, window.location.href)."],"exampleFix":"// before\ngetDocument({ url: someLocationObject });\n\n// after\ngetDocument({ url: new URL(someLocationObject.href) });\n// or\ngetDocument({ url: 'https://example.com/file.pdf' });","handlingStrategy":"type-guard","validationCode":"function normalizeUrl(u) {\n  if (u instanceof URL) return u;\n  if (typeof u === 'string') {\n    try { return new URL(u, typeof location !== 'undefined' ? location.href : undefined); }\n    catch { return null; }\n  }\n  return null;\n}\nconst url = normalizeUrl(source);\nif (!url) throw new Error('source must be a URL or URL string');\ngetDocument({ url });","typeGuard":"const isUrlInput = (v): v is string | URL =>\n  typeof v === 'string' || v instanceof URL;","tryCatchPattern":"try {\n  loadingTask = getDocument({ url });\n} catch (e) {\n  if (e.message.startsWith('Invalid PDF url data')) { /* fix source */ }\n  else throw e;\n}","preventionTips":["Always construct a URL object at the boundary: new URL(raw).","Prefer { data: Uint8Array } when you already have bytes.","Type getDocument's source param explicitly to URL | string | Uint8Array."],"tags":["getdocument","url","validation"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}