parcel-bundler/parcel · error · ThrowableDiagnostic

Could not get available port: ${err.message}

Error message

Could not get available port: ${err.message}

What it means

Thrown when the getPort() function (from the `port_finder` or similar library) rejects entirely during Parcel's serve/HMR port allocation. This is distinct from error [79] which handles the case where a port is found but differs from the requested one. Here, getPort() itself throws — meaning no port could be allocated at all, not even a fallback.

Source

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

  let https = !!command.https;
  if (command.cert && command.key) {
    https = {
      cert: command.cert,
      key: command.key,
    };
  }

  let serveOptions = false;
  let {host} = command;

  // Ensure port is valid and available
  let port = parsePort(command.port || '1234');
  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);
      }
    }

View on GitHub (pinned to 59484858a1)

Solutions

1. Check the --host value is valid: use 'localhost', '127.0.0.1', '0.0.0.0', or omit it.
2. Verify network interface availability: `ifconfig` or `ip addr`.
3. Try a different port range that's not in heavy use.
4. Check system-level port limits: `ulimit -n`, `/proc/sys/net/ipv4/ip_local_port_range`.
5. Disable security software temporarily to test if it's blocking port allocation.

Example fix

// before
$ parcel serve --host invalid.hostname.local --port 3000
// Error: Could not get available port: ...

// after
$ parcel serve --host localhost --port 3000

// Pre-check: verify host is valid and network is accessible
const net = require('net');

function validateServeHost(host) {
  if (!host) return true; // default
  // Check if it's a valid IP or hostname
  if (net.isIP(host) === 0) {
    // Not an IP — check if it resolves
    const dns = require('dns').promises;
    return dns.lookup(host).then(() => true).catch(() => {
      throw new Error(`Host '${host}' does not resolve to a local interface`);
    });
  }
  return true;
}

When it happens

Trigger: Parcel calls getPort({port, host}) during serve or HMR setup. If getPort throws (e.g., the host is invalid, network interfaces are inaccessible, or EADDRINUSE cascades exhaust the port range), the catch block wraps the error in a ThrowableDiagnostic with the original error's message and stack.

Common situations: Invalid host value (e.g., a hostname that doesn't resolve to a local interface). Network restrictions in containers or sandboxed environments preventing port binding. System-level port exhaustion (thousands of connections in TIME_WAIT). Permission denied for binding to ports below 1024 without root. Firewall or security software blocking port allocation.

Related errors

• Port "${originalPort}" could not be used
• Port ${portValue} is not a valid integer.
• Entry ${entry} does not exist
• npm failed to install modules: ${e.message} - ${stderr.join(
• Yarn failed to install modules: ${e.message}

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