gatsbyjs/gatsby · critical

${err}

Error message

${err}

What it means

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.

Source

Thrown at packages/gatsby/src/utils/detect-port-in-use-and-prompt.ts:10

import detectPort from "detect-port"
import report from "gatsby-cli/lib/reporter"
import prompts from "prompts"

export const detectPortInUseAndPrompt = async (
  port: number,
  hostname?: string
): Promise<number> => {
  const detectedPort = await detectPort({ port, hostname }).catch(
    (err: Error) => report.panic(err)
  )
  if (port !== detectedPort) {
    report.log(`\nSomething is already running at port ${port}`)
    const response = await prompts({
      type: `confirm`,
      name: `newPort`,
      message: `Would you like to run the app at another port instead?`,
      initial: true,
    })
    if (response.newPort) {
      port = detectedPort
    } else {
      throw new Error(`USER_REJECTED`)
    }
  }

  return port
}

View on GitHub (pinned to 8b06340921)

Solutions

1. Read the inner error object in the panic output for the specific cause.
2. Try a different port (--port flag) or omit the hostname to use the default.
3. If in a container/CI, ensure the networking stack allows local port binding and probing.
4. Update detect-port and Gatsby to latest versions.

// Pre-check port availability with a simpler method
const net = require('net')

function isPortAvailable(port, hostname) {
  hostname = hostname || '0.0.0.0'
  return new Promise(function(resolve) {
    const tester = net.createServer()
    tester.once('error', function() { resolve(false) })
    tester.once('listening', function() {
      tester.close(function() { resolve(true) })
    })
    tester.listen(port, hostname)
  })
}

// Wrap port detection and provide fallback
var port = program.port
try {
  port = await detectPortInUseAndPrompt(port, program.host)
} catch (err) {
  console.error('Port detection failed: ' + err.message + '. Trying alternative port.')
  port = 9000 // fallback
}

When it happens

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

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

Related errors

• {"fetchError":"Could not fetch ${pathOrUrl} from official re
• Something went wrong when trying to add the plugins to the p
• Cannot access Contentful space "${maskText(pluginOptions.spa
• url passed to createRemoteFileNode is either missing or not
• Source GraphQL API: HTTP error ${response.status} ${response

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/6043974dc3040e79. Report an issue: GitHub.