{"record":{"id":"9443859c8f3470a2","repo":"facebook/docusaurus","slug":"could-not-find-an-open-port-at-host","errorCode":null,"errorMessage":"Could not find an open port at ${host}.","messagePattern":"Could not find an open port at (.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus/src/server/getHostPort.ts","lineNumber":88,"sourceCode":"    if (!isInteractive) {\n      logger.error(message);\n      return null;\n    }\n    clearConsole();\n    const existingProcess = getProcessForPort(defaultPort);\n    const {shouldChangePort} = (await prompts({\n      type: 'confirm',\n      name: 'shouldChangePort',\n      message: logger.yellow(`${logger.bold('[WARNING]')} ${message}${\n        existingProcess ? ` Probably:\\n  ${existingProcess}` : ''\n      }\n\nWould you like to run the app on another port instead?`),\n      initial: true,\n    })) as {shouldChangePort: boolean};\n    return shouldChangePort ? port : null;\n  } catch (err) {\n    throw new Error(\n      logger.interpolate`Could not find an open port at ${host}.`,\n      {cause: err},\n    );\n  }\n}\n\nexport type HostPortOptions = {\n  host?: string;\n  port?: string;\n};\n\nexport async function getHostPort(options: HostPortOptions): Promise<{\n  host: string;\n  port: number | null;\n}> {\n  const host = options.host ?? 'localhost';\n  const basePort = options.port ? parseInt(options.port, 10) : DEFAULT_PORT;\n  const port = await choosePort(host, basePort);","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus/src/server/getHostPort.ts#L70-L106","documentation":"Thrown by `choosePort` when the underlying `detect-port` call (or the interactive prompt) throws — i.e. the host/port combination could not be resolved to a free port. The original error is attached as `cause`. It is a fatal dev-server startup failure, not the normal 'port in use' interactive flow.","triggerScenarios":"The `detect({port, hostname})` promise rejects (e.g. invalid host, network error), or the `prompts` call throws in a non-interactive/CI shell. The catch at getHostPort.ts:87 wraps these into a single 'Could not find an open port at <host>' error.","commonSituations":"Passing an unresolvable `--host` value; running in a sandboxed CI without TTY where prompts abort; Docker/port-binding conflicts; a host that the OS cannot bind (e.g. a hostname not mapped to a local interface).","solutions":["Specify a different port: `--port 3001` or set `PORT` in env.","Use `--host localhost` or `--host 127.0.0.1` instead of a custom hostname.","In CI, pass `--no-open` and ensure a TTY or pre-allocate a known-free port.","Free the occupied port or kill the stale process before retrying."],"exampleFix":"// before\ndocusaurus start --host my.custom.host\n// after\ndocusaurus start --host 127.0.0.1 --port 3001","handlingStrategy":"retry","validationCode":"import detect from 'detect-port';\nasync function findFreePort(preferred: number) {\n  const port = await detect({port: preferred});\n  if (port === preferred) return port;\n  return detect({port: 0}); // ask OS for any free port\n}","typeGuard":null,"tryCatchPattern":"try {\n  const {host, port} = await getHostPort({host: '127.0.0.1', port: '3000'});\n} catch (e) {\n  console.error('Port resolution failed; falling back to ephemeral port');\n  // re-run with port: 0\n}","preventionTips":["Pin `--host 127.0.0.1` in shared scripts.","In CI, pass a known-free port and `--no-open`.","Avoid exotic hostnames the OS cannot bind."],"tags":["dev-server","network","port","startup"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}