windmill-labs/windmill · error

Port ${requested} is already in use${holderHint}. Using port

Error message

Port ${requested} is already in use${holderHint}. Using port ${port} instead.

What it means

Emitted by resolveBindPort: the requested port is occupied (holderHint names the holding process when identifiable), so the probe shifted up (max +20) and bound the first free port, which is reported. Only embedders hardcoding the original port are affected; the dev session otherwise works.

Source

Thrown at cli/src/utils/port-probe.ts:130

 * at +20 to avoid silently scanning the whole 4xxx range. On shift, logs a
 * prominent warning naming the holder if we can find it.
 *
 * Returns the chosen port (== requested when it was already free).
 */
export async function resolveBindPort(
  requested: number,
  flagLabel: string,
  log: { info: (msg: string) => void; warn: (msg: string) => void },
): Promise<number> {
  const MAX_SHIFT = 20;
  for (let port = requested; port < requested + MAX_SHIFT; port++) {
    if (await isPortFreeOnBothStacks(port)) {
      if (port !== requested) {
        const holder = findPortHolder(requested);
        const holderHint = holder
          ? ` (held by PID ${holder.pid} \`${holder.command}\`)`
          : "";
        log.warn(
          `Port ${requested} is already in use${holderHint}. Using port ${port} instead.`,
        );
        log.info(
          `If you need port ${requested} stable (e.g. a launch.json entry pinned to it), stop the holder and re-run with ${flagLabel} ${requested}.`,
        );
      }
      return port;
    }
  }
  throw new Error(
    `Could not find a free port in the range ${requested}-${requested + MAX_SHIFT - 1}. Stop a holder or pass ${flagLabel} <other>.`,
  );
}

/**
 * The host string we bind to. Explicit IPv4 — `localhost` resolves to
 * 127.0.0.1 first on every platform we care about, and binding both stacks
 * relies on platform-specific IPV6_V6ONLY behaviour we don't want to debug.

View on GitHub (pinned to e474e8803c)

Solutions

  1. Stop the process holding the port (named in holderHint)
  2. Request a different port explicitly via the corresponding flag
  3. Consume the reported port instead of assuming the requested one
Defensive patterns

Strategy: fallback

When it happens

Trigger: Thrown at cli/src/utils/port-probe.ts:130 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/d8cafc03e78df6be. Report an issue: GitHub.