denoland/deno · error · DOMException

SyntaxError

SyntaxError

Error message

e.message

What it means

The WebTransport constructor parses its URL argument with the standard URL parser (relative to the module's location); if parsing fails, the underlying TypeError's message is rewrapped as a DOMException named SyntaxError in ext/web/webtransport.js. Typical causes: missing or unsupported scheme (only https/http-style absolute URLs parse here), spaces or invalid characters, or a bad port. The failure is synchronous, at `new WebTransport(url)`.

Source

Thrown at ext/web/webtransport.js:200

    let promise;

    if (url === illegalConstructorKey) {
      promise = PromiseResolve(options);
    } else {
      const prefix = "Failed to construct 'WebTransport'";
      webidl.requiredArguments(arguments.length, 1, prefix);
      url = webidl.converters.USVString(url, prefix, "Argument 1");
      options = webidl.converters.WebTransportOptions(
        options,
        prefix,
        "Argument 2",
      );

      let parsedURL;
      try {
        parsedURL = new URL(url, getLocationHref());
      } catch (e) {
        throw new DOMException(e.message, "SyntaxError");
      }

      switch (options.congestionControl) {
        case "throughput":
          this.#congestionControl = "throughput";
          break;
        case "low-latency":
          this.#congestionControl = "low-latency";
          break;
        default:
          this.#congestionControl = "default";
      }
      this.#anticipatedConcurrentIncomingBidirectionalStreams =
        options.anticipatedConcurrentIncomingBidirectionalStreams;
      this.#anticipatedConcurrentIncomingUnidirectionalStreams =
        options.anticipatedConcurrentIncomingUnidirectionalStreams;

      promise = PromisePrototypeThen(

View on GitHub (pinned to 9ad36f7a2c)

Solutions

1. Use an absolute URL with scheme and host, e.g. "https://example.com:443/wt".
2. Normalize first: `const u = new URL(raw); u.protocol = "https:"; new WebTransport(u.href)`.
3. Trim whitespace and validate env-provided URLs before constructing.
4. URL-encode the path components that may contain special characters.

Example fix

// before
const wt = new WebTransport(`${HOST}:${PORT}/wt`); // HOST lacks scheme

// after
const wt = new WebTransport(`https://${HOST}:${PORT}/wt`);

let parsed;
try {
  parsed = new URL(rawUrl);
  parsed.protocol = "https:";
} catch {
  throw new Error(`invalid WebTransport URL: ${rawUrl}`);
}
const wt = new WebTransport(parsed.href);

function isAbsoluteHttpsUrl(u) {
  try { return new URL(u).protocol === "https:"; } catch { return false; }
}

try { const wt = new WebTransport(url); } catch (e) { if (e instanceof DOMException && e.name === "SyntaxError") throw new Error(`bad endpoint URL: ${url}`); throw e; }

When it happens

Trigger: new WebTransport("example.com:443") — missing https:// scheme; URLs with unencoded spaces or invalid port like https://h:abc; building URLs by string concatenation that drops the scheme; relative paths like "/wt" which cannot resolve to a ws/wt endpoint.

Common situations: Reading the URL from an env var that is empty or lacks the scheme; joining host and path with malformed separators; copying a hostname from a config UI that strips the protocol; trailing whitespace from a config file.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• SyntaxError
• NotSupportedError
• WebTransport is not connected
• SyntaxError
• Invalid header: length must be 2, but is ${header.length}

AI-assisted analysis of denoland/deno@9ad36f7a2c (2026-08-20). Data as JSON: /api/errors/775b20d009b1d4f0. Report an issue: GitHub.