{"record":{"id":"dc0091bb3984f289","repo":"websockets/ws","slug":"invalid-url-address","errorCode":null,"errorMessage":"Invalid URL: ${address}","messagePattern":"Invalid URL: (.+?)","errorType":"exception","errorClass":"SyntaxError","httpStatus":null,"severity":"error","filePath":"lib/websocket.js","lineNumber":709,"sourceCode":"  websocket._autoPong = opts.autoPong;\n  websocket._closeTimeout = opts.closeTimeout;\n\n  if (!protocolVersions.includes(opts.protocolVersion)) {\n    throw new RangeError(\n      `Unsupported protocol version: ${opts.protocolVersion} ` +\n        `(supported versions: ${protocolVersions.join(', ')})`\n    );\n  }\n\n  let parsedUrl;\n\n  if (address instanceof URL) {\n    parsedUrl = address;\n  } else {\n    try {\n      parsedUrl = new URL(address);\n    } catch {\n      throw new SyntaxError(`Invalid URL: ${address}`);\n    }\n  }\n\n  if (parsedUrl.protocol === 'http:') {\n    parsedUrl.protocol = 'ws:';\n  } else if (parsedUrl.protocol === 'https:') {\n    parsedUrl.protocol = 'wss:';\n  }\n\n  websocket._url = parsedUrl.href;\n\n  const isSecure = parsedUrl.protocol === 'wss:';\n  const isIpcUrl = parsedUrl.protocol === 'ws+unix:';\n  let invalidUrlMessage;\n\n  if (parsedUrl.protocol !== 'ws:' && !isSecure && !isIpcUrl) {\n    invalidUrlMessage =\n      'The URL\\'s protocol must be one of \"ws:\", \"wss:\", ' +","sourceCodeStart":691,"sourceCodeEnd":727,"githubUrl":"https://github.com/websockets/ws/blob/c791e707eab3c13dd9a261d2479c3cc4a49a6fed/lib/websocket.js#L691-L727","documentation":"Thrown by initAsClient() at websocket.js:706-710 when the address argument cannot be parsed by `new URL(address)`. The constructor accepts a string or a URL object; if it is a string, the WHATWG URL parser runs and any failure (catch block at line 708) is converted into a SyntaxError with the original address in the message. This happens synchronously, during WebSocket construction.","triggerScenarios":"Passing a malformed string to new WebSocket(address), e.g. 'localhost:8080' (no scheme), 'ws://[broken', '' (empty), or a value with embedded spaces/control characters. If address is already a URL instance it is used directly (line 703-704) and never hits this branch; only strings go through the try/catch.","commonSituations":"Forgetting the ws:// or wss:// scheme (a bare host:port is not a valid URL); constructing the URL from env vars that are empty or missing; a config typo; user input that wasn't validated; relative paths passed as the address.","solutions":["Always include the scheme: new WebSocket('ws://localhost:8080') or 'wss://host/path'.","Validate/normalize the address before constructing: new URL(address) in your own try/catch, or build it from components.","If the address may be incomplete, prefix a default scheme and host before passing it in."],"exampleFix":"// before\nconst ws = new WebSocket('localhost:8080/ws'); // no scheme -> throws\n\n// after\nconst ws = new WebSocket('ws://localhost:8080/ws');","handlingStrategy":"validation","validationCode":"function toWebSocketUrl(address) {\n  if (address instanceof URL) return address;\n  // ensure a scheme is present\n  if (!/^[a-z][a-z0-9+.-]*:///i.test(address)) {\n    address = 'ws://' + address;\n  }\n  return new URL(address); // throws if still invalid\n}","typeGuard":"function isParseableWsUrl(address) {\n  try { new URL(address); return true; } catch { return false; }\n}","tryCatchPattern":null,"preventionTips":["Always include the scheme (ws:// or wss://) in address strings.","Validate addresses with new URL() in a try/catch before constructing the WebSocket.","Normalize config/env-sourced URLs (add default scheme/host) before passing them in."],"tags":["websocket","client","url","validation","configuration"],"backgroundTag":null,"analyzedSha":"c791e707eab3c13dd9a261d2479c3cc4a49a6fed","analyzedAt":"2026-08-06T19:07:51.047Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}