{"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/ae1de54330cef77e487548890fabfeb9aae1d83d/lib/websocket.js#L691-L727","documentation":"Thrown by initAsClient() (lib/websocket.js:706-711) when the address argument cannot be parsed by `new URL(address)`. The constructor first tries to interpret address as a URL; if that throws, ws wraps it in SyntaxError('Invalid URL: ' + address). Note this fires before the protocol is validated, so even a parseable but wrong-scheme URL will produce a different error ('The URL\\'s protocol must be one of ...'); this specific message means URL parsing itself failed.","triggerScenarios":"Calling new WebSocket(someString) where someString is not a valid URL (missing scheme, unencoded spaces, malformed host), e.g. 'localhost:8080' (no scheme), 'wss://', or user input that was never validated.","commonSituations":"Omitting the ws:// or wss:// scheme; building URLs via string concatenation without encoding; reading the URL from untrusted config/env vars; passing a host:port pair without a protocol.","solutions":["Always include a scheme: 'ws://host:port/path' or 'wss://host/path'.","Construct the URL with `new URL(...)` yourself before passing it (or pass a URL object, which skips the failing branch).","Validate user/config input and reject or fix missing schemes upstream."],"exampleFix":"// before\nnew WebSocket('localhost:8080/chat');\n\n// after\nnew WebSocket('ws://localhost:8080/chat');","handlingStrategy":"validation","validationCode":"function parseWsUrl(address) {\n  let url;\n  try {\n    url = address instanceof URL ? address : new URL(address);\n  } catch {\n    throw new SyntaxError(`Invalid URL: ${address}`);\n  }\n  if (url.protocol === 'http:') url.protocol = 'ws:';\n  else if (url.protocol === 'https:') url.protocol = 'wss:';\n  if (!['ws:', 'wss:', 'ws+unix:'].includes(url.protocol)) {\n    throw new SyntaxError('Unsupported scheme');\n  }\n  return url;\n}","typeGuard":"function isParseableWsUrl(address) {\n  try {\n    const u = address instanceof URL ? address : new URL(address);\n    return ['ws:', 'wss:', 'http:', 'https:', 'ws+unix:'].includes(u.protocol);\n  } catch {\n    return false;\n  }\n}","tryCatchPattern":"try {\n  new WebSocket(address);\n} catch (err) {\n  if (/Invalid URL/.test(err.message)) {\n    // fix the scheme/encoding and retry, or surface to user\n  } else {\n    throw err;\n  }\n}","preventionTips":["Always include a scheme (ws:// or wss://) in the address.","Validate/encode untrusted URL input with `new URL()` before passing it.","Pass a URL object directly to skip re-parsing and get clearer upstream errors."],"tags":["websocket","client","url","input-validation"],"analyzedSha":"ae1de54330cef77e487548890fabfeb9aae1d83d","analyzedAt":"2026-08-03T19:11:18.437Z","schemaVersion":2}