TypeError: Failed to construct 'URL': Invalid URL

The exact error string

new URL("/api/users");
// Uncaught TypeError: Failed to construct 'URL': Invalid URL

new URL("example.com");
// Uncaught TypeError: Failed to construct 'URL': Invalid URL
//   -> no protocol, so this isn't a recognizable absolute URL

What it actually looks like

Why this throws instead of returning something empty

Unlike most JavaScript string handling, the URL constructor validates its input against the URL spec immediately and synchronously — there's no "empty URL" fallback the way Number("abc") gives you NaN. If the input isn't a parseable absolute URL (and no base was given to resolve a relative one against), it throws right there, which is exactly why this needs a try/catch around any URL coming from outside your control.

Cause 1: a relative path with no base

new URL("/api/users");
// ❌ relative path — no scheme, no host

new URL("/api/users", "https://example.com");   // ✅ two-argument form
// -> https://example.com/api/users

new URL("/api/users", window.location.origin);   // ✅ resolve against the current page

Cause 2: a missing protocol

new URL("example.com");
// ❌ looks like a bare hostname, not a full URL

new URL("https://example.com");   // ✅ explicit protocol

// or detect and normalize user-typed input:
function toAbsoluteUrl(input) {
  return /^https?:\/\//i.test(input) ? input : "https://" + input;
}
new URL(toAbsoluteUrl("example.com"));   // ✅

Cause 3: unvalidated user input

function isValidUrl(value) {
  try {
    new URL(value);
    return true;
  } catch {
    return false;   // ✅ bad input is expected, not exceptional — handle it, don't crash
  }
}

if (isValidUrl(userInput)) {
  const url = new URL(userInput);
  // ... use it
} else {
  showError("Please enter a valid URL, including https://");
}

Cause 4: a broken template literal

const base = "https://api.example.com";   // no trailing slash
const path = "users";
new URL(`${base}/${path}`);   // ✅ https://api.example.com/users

const endpoint = undefined;
new URL(`${base}/${endpoint}`);
// ❌ builds "https://api.example.com/undefined" — technically parses,
//    but is not the URL you meant; log the built string to catch this

The same failure, two different messages

The wording in the heading of this page is browser-specific. The Failed to construct 'URL': prefix comes from the WebIDL layer that wraps constructors in the browser, and Node has no such layer — so identical code produces a visibly different string depending on where it runs:

// Chrome 152 (and any Chromium browser)
Uncaught TypeError: Failed to construct 'URL': Invalid URL

// Node.js v24.15.0 — same bug, different text, plus a machine-readable code
TypeError: Invalid URL
    at new URL (node:internal/url:825:25) {
  code: 'ERR_INVALID_URL',
  input: '/api/users'
}

Two practical consequences. First, if you searched one form and found nothing useful, search the other. Second, Node's version is strictly more helpful for debugging: it attaches code: 'ERR_INVALID_URL' (stable across versions, so safe to branch on) and an input property containing the exact string that failed — which is the one thing the browser message never tells you.

try {
  new URL(value);
} catch (err) {
  if (err.code === "ERR_INVALID_URL") {
    console.error("bad URL:", err.input);   // ✅ Node prints the offending string
  }
  throw err;
}

Check without throwing: URL.canParse() and URL.parse()

The try/catch in Cause 3 above is no longer the only option. Two static methods now answer the same question without using exceptions for control flow:

URL.canParse("/api/users");                          // false — returns a boolean, never throws
URL.canParse("/api/users", "https://api.example.com"); // true  — base makes it resolvable

URL.parse("/api/users");                             // null instead of throwing
const url = URL.parse(userInput, base);
if (url === null) {
  showError("Please enter a valid URL, including https://");
} else {
  fetch(url);                                        // ✅ already a URL object
}

Both take the same (input, base) arguments as the constructor. URL.canParse() landed in Chrome 120, Firefox 115, Safari 17 and Node 19.9; the static URL.parse() is newer — Chrome 126, Firefox 126, Safari 18 and Node 22.1. Prefer URL.parse() where your baseline allows it: canParse() followed by new URL() parses the string twice, while parse() validates and gives you the object in one pass. If you must support older targets, keep the try/catch.

The base argument: a trailing slash changes the answer

Once you start passing a base URL to fix Cause 1, a subtler bug replaces the original one. The base is resolved using the normal relative-URL rules, which means the last path segment of the base is discarded unless the base ends in a slash:

new URL("users", "https://api.example.com/v1/").href
// ✅ "https://api.example.com/v1/users"   — base ends in "/", v1 is a directory

new URL("users", "https://api.example.com/v1").href
// ❌ "https://api.example.com/users"      — no slash, so "v1" is replaced

new URL("/users", "https://api.example.com/v1/").href
// ❌ "https://api.example.com/users"      — a leading "/" ignores the base path entirely

All three of these parse successfully, so nothing throws — you get a 404 from your API instead, which is a much longer debugging session than an exception would have been. Verified identically on Chrome 152 and Node v24.15.0. The rule worth memorising: base paths end in a slash, relative paths do not begin with one. When a request 404s just after you added a base URL, log url.href before the fetch and this will be visible immediately.

Common variants at a glance

Debugging checklist

• ✓ Log the exact string right before new URL(...) runs
• ✓ Relative path? Add the base as the second argument
• ✓ No http(s)://? Add it before constructing
• ✓ Value comes from a user or external source? Wrap in try/catch
• ✓ Built with a template literal? Confirm no piece is undefined and separators are correct

References

• URL() constructor (MDN)
• URL Standard (WHATWG)