{"record":{"id":"8d69445529ea3808","repo":"parcel-bundler/parcel","slug":"could-not-get-available-port-err-message","errorCode":null,"errorMessage":"Could not get available port: ${err.message}","messagePattern":"Could not get available port: (.+?)","errorType":"exception","errorClass":"ThrowableDiagnostic","httpStatus":null,"severity":"error","filePath":"packages/core/parcel/src/cli.js","lineNumber":466,"sourceCode":"  let https = !!command.https;\n  if (command.cert && command.key) {\n    https = {\n      cert: command.cert,\n      key: command.key,\n    };\n  }\n\n  let serveOptions = false;\n  let {host} = command;\n\n  // Ensure port is valid and available\n  let port = parsePort(command.port || '1234');\n  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    }","sourceCodeStart":448,"sourceCodeEnd":484,"githubUrl":"https://github.com/parcel-bundler/parcel/blob/59484858a1a0bcbb71f74088956bb437a2db6505/packages/core/parcel/src/cli.js#L448-L484","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the --host value is valid: use 'localhost', '127.0.0.1', '0.0.0.0', or omit it.","Verify network interface availability: `ifconfig` or `ip addr`.","Try a different port range that's not in heavy use.","Check system-level port limits: `ulimit -n`, `/proc/sys/net/ipv4/ip_local_port_range`.","Disable security software temporarily to test if it's blocking port allocation."],"exampleFix":"// before\n$ parcel serve --host invalid.hostname.local --port 3000\n// Error: Could not get available port: ...\n\n// after\n$ parcel serve --host localhost --port 3000","handlingStrategy":"try-catch","validationCode":"// Pre-check: verify host is valid and network is accessible\nconst net = require('net');\n\nfunction validateServeHost(host) {\n  if (!host) return true; // default\n  // Check if it's a valid IP or hostname\n  if (net.isIP(host) === 0) {\n    // Not an IP — check if it resolves\n    const dns = require('dns').promises;\n    return dns.lookup(host).then(() => true).catch(() => {\n      throw new Error(`Host '${host}' does not resolve to a local interface`);\n    });\n  }\n  return true;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use standard host values: 'localhost', '127.0.0.1', or '0.0.0.0'.","Verify network interfaces are available in containers: `ip addr` or `ifconfig`.","Check firewall/security software isn't blocking port allocation.","Ensure sufficient file descriptors: `ulimit -n`."],"tags":["cli","port","network","serve","hmr","getport"],"backgroundTag":null,"analyzedSha":"59484858a1a0bcbb71f74088956bb437a2db6505","analyzedAt":"2026-08-13T04:06:35.925Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}