{"record":{"id":"6043974dc3040e79","repo":"gatsbyjs/gatsby","slug":"err-604397","errorCode":null,"errorMessage":"${err}","messagePattern":"\\$\\{err\\}","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/gatsby/src/utils/detect-port-in-use-and-prompt.ts","lineNumber":10,"sourceCode":"import detectPort from \"detect-port\"\nimport report from \"gatsby-cli/lib/reporter\"\nimport prompts from \"prompts\"\n\nexport const detectPortInUseAndPrompt = async (\n  port: number,\n  hostname?: string\n): Promise<number> => {\n  const detectedPort = await detectPort({ port, hostname }).catch(\n    (err: Error) => report.panic(err)\n  )\n  if (port !== detectedPort) {\n    report.log(`\\nSomething is already running at port ${port}`)\n    const response = await prompts({\n      type: `confirm`,\n      name: `newPort`,\n      message: `Would you like to run the app at another port instead?`,\n      initial: true,\n    })\n    if (response.newPort) {\n      port = detectedPort\n    } else {\n      throw new Error(`USER_REJECTED`)\n    }\n  }\n\n  return port\n}","sourceCodeStart":1,"sourceCodeEnd":28,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/utils/detect-port-in-use-and-prompt.ts#L1-L28","documentation":"During develop startup, Gatsby uses the detect-port library to check if the configured port (default 8000) is available. If detect-port itself throws (not just finds the port busy -- that is handled separately with a prompt), the error propagates as a panic. The actual message is the detect-port error object.","triggerScenarios":"detectPort({ port, hostname }) rejects -- this is rare and happens on system-level issues such as inability to probe ports, permissions errors on the networking stack, or an invalid hostname. The normal 'port busy' case is handled by the port !== detectedPort branch, not this catch.","commonSituations":"Passing an invalid hostname (e.g. a malformed string). System networking stack issues. Containerized environment where port probing is restricted. A bug in detect-port with certain OS/Node combinations. DNS resolution failure for the hostname.","solutions":["Read the inner error object in the panic output for the specific cause.","Try a different port (--port flag) or omit the hostname to use the default.","If in a container/CI, ensure the networking stack allows local port binding and probing.","Update detect-port and Gatsby to latest versions."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-check port availability with a simpler method\nconst net = require('net')\n\nfunction isPortAvailable(port, hostname) {\n  hostname = hostname || '0.0.0.0'\n  return new Promise(function(resolve) {\n    const tester = net.createServer()\n    tester.once('error', function() { resolve(false) })\n    tester.once('listening', function() {\n      tester.close(function() { resolve(true) })\n    })\n    tester.listen(port, hostname)\n  })\n}","typeGuard":null,"tryCatchPattern":"// Wrap port detection and provide fallback\nvar port = program.port\ntry {\n  port = await detectPortInUseAndPrompt(port, program.host)\n} catch (err) {\n  console.error('Port detection failed: ' + err.message + '. Trying alternative port.')\n  port = 9000 // fallback\n}","preventionTips":["Use a reliable port (--port) known to be free.","Omit custom hostname if not needed to avoid DNS resolution issues.","In containers/CI, ensure the networking stack allows port probing.","Keep detect-port and Gatsby updated."],"tags":["network","port","develop","detect-port"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}