parcel-bundler/parcel · error · Error

Port "${originalPort}" could not be used

Error message

Port "${originalPort}" could not be used

What it means

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.

Source

Thrown at packages/core/parcel/src/cli.js:479

  let originalPort = port;
  if (command.name() === 'serve' || command.hmr) {
    try {
      port = await getPort({port, host});
    } catch (err) {
      throw new ThrowableDiagnostic({
        diagnostic: {
          message: `Could not get available port: ${err.message}`,
          origin: 'parcel',
          stack: err.stack,
        },
      });
    }

    if (port !== originalPort) {
      let errorMessage = `Port "${originalPort}" could not be used`;
      if (command.port != null) {
        // Throw the error if the user defined a custom port
        throw new Error(errorMessage);
      } else {
        // Parcel logger is not set up at this point, so just use native INTERNAL_ORIGINAL_CONSOLE
        INTERNAL_ORIGINAL_CONSOLE.warn(errorMessage);
      }
    }
  }

  if (command.name() === 'serve') {
    let {publicUrl, cors} = command;

    serveOptions = {
      https,
      port,
      host,
      publicUrl,
      cors,
    };
  }

View on GitHub (pinned to 59484858a1)

Solutions

1. Find and kill the process using the port: `lsof -i :3000` then `kill <PID>` (macOS/Linux) or `netstat -ano | findstr :3000` (Windows).
2. Use a different port: `parcel serve --port 3001`.
3. Remove the --port flag to let Parcel auto-select an available port.
4. Check for orphaned Node processes: `ps aux | grep parcel` and kill stale ones.

Example fix

// before
$ parcel serve --port 3000
// Error: Port "3000" could not be used

// after: either free the port or use another
$ lsof -ti :3000 | xargs kill -9
$ parcel serve --port 3000
// OR
$ parcel serve --port 3001

// Check if a port is available before starting Parcel
const net = require('net');

function isPortAvailable(port, host) {
  return new Promise((resolve) => {
    let tester = net.createServer()
      .once('error', () => resolve(false))
      .once('listening', () => {
        tester.once('close', () => resolve(true)).close();
      })
      .listen(port, host);
  });
}

// Usage before starting Parcel:
const port = 3000;
if (!(await isPortAvailable(port, 'localhost'))) {
  console.error(`Port ${port} is in use. Try another port or kill the process.`);
  process.exit(1);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not get available port: ${err.message}
• Port ${portValue} is not a valid integer.
• Entry ${entry} does not exist
• Feature flag ${name} must be set to true or false
• A Parcel link could not be found!

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/3b06c8b9b09cd3dd. Report an issue: GitHub.