{"record":{"id":"3b06c8b9b09cd3dd","repo":"parcel-bundler/parcel","slug":"port-originalport-could-not-be-used","errorCode":null,"errorMessage":"Port \"${originalPort}\" could not be used","messagePattern":"Port \"(.+?)\" could not be used","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/parcel/src/cli.js","lineNumber":479,"sourceCode":"  let originalPort = port;\n  if (command.name() === 'serve' || command.hmr) {\n    try {\n      port = await getPort({port, host});\n    } catch (err) {\n      throw new ThrowableDiagnostic({\n        diagnostic: {\n          message: `Could not get available port: ${err.message}`,\n          origin: 'parcel',\n          stack: err.stack,\n        },\n      });\n    }\n\n    if (port !== originalPort) {\n      let errorMessage = `Port \"${originalPort}\" could not be used`;\n      if (command.port != null) {\n        // Throw the error if the user defined a custom port\n        throw new Error(errorMessage);\n      } else {\n        // Parcel logger is not set up at this point, so just use native INTERNAL_ORIGINAL_CONSOLE\n        INTERNAL_ORIGINAL_CONSOLE.warn(errorMessage);\n      }\n    }\n  }\n\n  if (command.name() === 'serve') {\n    let {publicUrl, cors} = command;\n\n    serveOptions = {\n      https,\n      port,\n      host,\n      publicUrl,\n      cors,\n    };\n  }","sourceCodeStart":461,"sourceCodeEnd":497,"githubUrl":"https://github.com/parcel-bundler/parcel/blob/59484858a1a0bcbb71f74088956bb437a2db6505/packages/core/parcel/src/cli.js#L461-L497","documentation":"Thrown during serve/HMR setup when the user explicitly provided a --port argument, but that port is already in use and getPort() returned a different available port. The code detects the mismatch (`port !== originalPort`), and since `command.port != null` (user specified it), it throws an error rather than silently switching. If the port was the default '1234' (not user-specified), it only warns.","triggerScenarios":"User runs `parcel serve --port 3000`. Port 3000 is occupied by another process. getPort() finds port 3001 instead. Because command.port is not null (user specified 3000), the code throws 'Port \"3000\" could not be used'. If the user had NOT specified --port, the default 1234 would just warn and use the alternate port.","commonSituations":"Another dev server (webpack-dev-server, vite, Next.js, another Parcel instance) is already running on the same port. A background process or Docker container is bound to the port. The previous Parcel serve process didn't shut down cleanly (orphaned process). OS assigning the port to a TIME_WAIT connection.","solutions":["Find and kill the process using the port: `lsof -i :3000` then `kill <PID>` (macOS/Linux) or `netstat -ano | findstr :3000` (Windows).","Use a different port: `parcel serve --port 3001`.","Remove the --port flag to let Parcel auto-select an available port.","Check for orphaned Node processes: `ps aux | grep parcel` and kill stale ones."],"exampleFix":"// before\n$ parcel serve --port 3000\n// Error: Port \"3000\" could not be used\n\n// after: either free the port or use another\n$ lsof -ti :3000 | xargs kill -9\n$ parcel serve --port 3000\n// OR\n$ parcel serve --port 3001","handlingStrategy":"validation","validationCode":"// Check if a port is available before starting Parcel\nconst net = require('net');\n\nfunction isPortAvailable(port, host) {\n  return new Promise((resolve) => {\n    let tester = net.createServer()\n      .once('error', () => resolve(false))\n      .once('listening', () => {\n        tester.once('close', () => resolve(true)).close();\n      })\n      .listen(port, host);\n  });\n}\n\n// Usage before starting Parcel:\nconst port = 3000;\nif (!(await isPortAvailable(port, 'localhost'))) {\n  console.error(`Port ${port} is in use. Try another port or kill the process.`);\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check if the port is free before starting: `lsof -i :PORT` (macOS/Linux).","Kill orphaned dev server processes after stopping Parcel.","Use `parcel serve` without --port to let Parcel auto-select an available port.","In Docker, ensure port mappings don't conflict with other containers."],"tags":["cli","port","port-in-use","serve","eaddrinuse"],"backgroundTag":null,"analyzedSha":"59484858a1a0bcbb71f74088956bb437a2db6505","analyzedAt":"2026-08-13T04:06:35.925Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}