{"id":"c344e592076342c2","repo":"websockets/ws","slug":"one-and-only-one-of-the-port-server-or-nose","errorCode":null,"errorMessage":"One and only one of the \"port\", \"server\", or \"noServer\" options must be specified","messagePattern":"One and only one of the \"port\", \"server\", or \"noServer\" options must be specified","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"critical","filePath":"lib/websocket-server.js","lineNumber":96,"sourceCode":"      clientTracking: true,\n      closeTimeout: CLOSE_TIMEOUT,\n      verifyClient: null,\n      noServer: false,\n      backlog: null, // use default (511 as implemented in net.js)\n      server: null,\n      host: null,\n      path: null,\n      port: null,\n      WebSocket,\n      ...options\n    };\n\n    if (\n      (options.port == null && !options.server && !options.noServer) ||\n      (options.port != null && (options.server || options.noServer)) ||\n      (options.server && options.noServer)\n    ) {\n      throw new TypeError(\n        'One and only one of the \"port\", \"server\", or \"noServer\" options ' +\n          'must be specified'\n      );\n    }\n\n    if (options.port != null) {\n      this._server = http.createServer((req, res) => {\n        const body = http.STATUS_CODES[426];\n\n        res.writeHead(426, {\n          'Content-Length': body.length,\n          'Content-Type': 'text/plain'\n        });\n        res.end(body);\n      });\n      this._server.listen(\n        options.port,\n        options.host,","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/websockets/ws/blob/ae1de54330cef77e487548890fabfeb9aae1d83d/lib/websocket-server.js#L78-L114","documentation":"Thrown by the WebSocketServer constructor (lib/websocket-server.js:91-100) when the port/server/noServer options do not satisfy an exactly-one-of constraint. The library needs precisely one of: a port to create+listen its own HTTP server, a pre-existing http.Server passed via server, or noServer mode where you handle the 'upgrade' event yourself. Zero or more-than-one of these is a configuration error and throws TypeError immediately during construction.","triggerScenarios":"Calling new WebSocketServer({}) (none specified), new WebSocketServer({ port: 8080, server: httpServer }) (port + server), new WebSocketServer({ noServer: true, port: 8080 }) (noServer + port), or new WebSocketServer({ server: httpServer, noServer: true }) (server + noServer). The boolean expression at lines 91-95 explicitly forbids all but the three valid single-option combinations.","commonSituations":"Migrating from a standalone server to embedding in an existing Express/http server and forgetting to drop the port option; copy-pasting examples that combine noServer with a server; typos like noServer: 'true' (string) being truthy alongside port.","solutions":["Pick exactly one mode: { port } OR { server } OR { noServer: true }.","If embedding in an existing HTTP server, use { server: httpServer } and remove any port option.","If intercepting upgrades manually, use { noServer: true } and call wss.handleUpgrade() from your own 'upgrade' listener."],"exampleFix":"// before\nnew WebSocketServer({ port: 8080, server: httpServer });\n\n// after\nnew WebSocketServer({ server: httpServer });","handlingStrategy":"validation","validationCode":"function assertServerOptions(opts) {\n  const modes = ['port', 'server', 'noServer'].filter((k) => opts[k] != null && opts[k] !== false);\n  if (modes.length !== 1) {\n    throw new TypeError('Pass exactly one of port, server, or noServer');\n  }\n}","typeGuard":"function isValidServerOptions(opts) {\n  const has = (k) => opts[k] != null && opts[k] !== false;\n  const count = has('port') + has('server') + has('noServer');\n  return count === 1;\n}","tryCatchPattern":"try {\n  const wss = new WebSocketServer(opts);\n} catch (err) {\n  if (/port.*server.*noServer/.test(err.message)) {\n    // fix opts to pick exactly one mode, then retry\n  } else {\n    throw err;\n  }\n}","preventionTips":["Decide your server mode up front: standalone (port), embedded (server), or manual (noServer).","When migrating modes, delete the now-unused option instead of leaving it set.","Avoid truthy non-booleans (e.g. noServer: 'true') which still count as set."],"tags":["websocket-server","configuration","startup","input-validation"],"analyzedSha":"ae1de54330cef77e487548890fabfeb9aae1d83d","analyzedAt":"2026-08-03T19:11:18.437Z","schemaVersion":2}