{"record":{"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/c791e707eab3c13dd9a261d2479c3cc4a49a6fed/lib/websocket-server.js#L78-L114","documentation":"Thrown by the WebSocketServer constructor at websocket-server.js:91-100. The server needs exactly one way to receive upgrade requests: either it creates its own HTTP server (port), reuses an existing one (server), or defers upgrade handling entirely to the user (noServer). The XOR logic rejects zero options (nothing to listen on) and any combination of two or three (ambiguous ownership of the upgrade event).","triggerScenarios":"Constructing new WebSocketServer({}) with none of the three options; passing both { port: 8080, server: httpServer }; passing { server: httpServer, noServer: true }; passing { port: 8080, noServer: true }; or all three at once. The three-way XOR at lines 92-94 fires for any combination other than exactly one.","commonSituations":"Forgetting to pass any option (empty constructor); copy-pasting from an example that used `server` while also keeping a `port` from another example; migrating from port mode to noServer mode but forgetting to remove the old option; TypeScript users whose optional fields all evaluate to undefined.","solutions":["Pick exactly one: new WebSocketServer({ port: 8080 }) to create an internal server, new WebSocketServer({ server }) to attach to an existing HTTP server, or new WebSocketServer({ noServer: true }) to handle upgrades manually.","If migrating modes, delete the now-unused option keys rather than setting them to null/undefined (port == null covers both null and undefined via ==).","Double-check that no option is accidentally inherited from a spread/merge of another config object."],"exampleFix":"// before\nconst wss = new WebSocketServer({ port: 8080, server: httpServer });\n\n// after — use ONE mode only\nconst wss = new WebSocketServer({ server: httpServer });","handlingStrategy":"validation","validationCode":"function validateServerOptions(options) {\n  const modes = ['port', 'server', 'noServer']\n    .filter(k => options[k] != null && options[k] !== false);\n  if (modes.length !== 1) {\n    throw new TypeError(\n      'Pass exactly one of: { port }, { server }, or { noServer: true }'\n    );\n  }\n}","typeGuard":"function isSingleServerMode(options) {\n  const count =\n    (options.port != null ? 1 : 0) +\n    (options.server ? 1 : 0) +\n    (options.noServer ? 1 : 0);\n  return count === 1;\n}","tryCatchPattern":"try {\n  wss = new WebSocketServer(config);\n} catch (err) {\n  if (/port.*server.*noServer/.test(err.message)) {\n    // fix config to use exactly one mode, then retry\n    config = { noServer: true };\n    wss = new WebSocketServer(config);\n  } else throw err;\n}","preventionTips":["Decide your server mode up front and set exactly one of port/server/noServer.","When migrating modes, delete stale option keys rather than nulling them (port == null matches null and undefined).","Validate the config object with a single-mode check before constructing."],"tags":["websocket-server","configuration","constructor","validation"],"backgroundTag":null,"analyzedSha":"c791e707eab3c13dd9a261d2479c3cc4a49a6fed","analyzedAt":"2026-08-06T19:07:51.047Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}