{"record":{"id":"eac81544b6cb3693","repo":"windmill-labs/windmill","slug":"could-not-find-a-free-port-in-the-range-requeste","errorCode":null,"errorMessage":"Could not find a free port in the range ${requested}-${requested + MAX_SHIFT - 1}. Stop a holder or pass ${flagLabel} <other>.","messagePattern":"Could not find a free port in the range (.+?)-(.+?)\\. Stop a holder or pass (.+?) <other>\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/src/utils/port-probe.ts","lineNumber":140,"sourceCode":"  const MAX_SHIFT = 20;\n  for (let port = requested; port < requested + MAX_SHIFT; port++) {\n    if (await isPortFreeOnBothStacks(port)) {\n      if (port !== requested) {\n        const holder = findPortHolder(requested);\n        const holderHint = holder\n          ? ` (held by PID ${holder.pid} \\`${holder.command}\\`)`\n          : \"\";\n        log.warn(\n          `Port ${requested} is already in use${holderHint}. Using port ${port} instead.`,\n        );\n        log.info(\n          `If you need port ${requested} stable (e.g. a launch.json entry pinned to it), stop the holder and re-run with ${flagLabel} ${requested}.`,\n        );\n      }\n      return port;\n    }\n  }\n  throw new Error(\n    `Could not find a free port in the range ${requested}-${requested + MAX_SHIFT - 1}. Stop a holder or pass ${flagLabel} <other>.`,\n  );\n}\n\n/**\n * The host string we bind to. Explicit IPv4 — `localhost` resolves to\n * 127.0.0.1 first on every platform we care about, and binding both stacks\n * relies on platform-specific IPV6_V6ONLY behaviour we don't want to debug.\n */\nexport const BIND_HOST = \"0.0.0.0\" as const;\n","sourceCodeStart":122,"sourceCodeEnd":151,"githubUrl":"https://github.com/windmill-labs/windmill/blob/e474e8803ce2ff5c2df09a58dab51d45f5c922ca/cli/src/utils/port-probe.ts#L122-L151","documentation":"resolveBindPort probes ports for the wmill dev servers (frontend/backend, e.g. `wmill dev`/`wmill proxy`). Starting from the requested port it probes up to MAX_SHIFT consecutive ports; if every port in the range requested..requested+MAX_SHIFT-1 is occupied, it throws this Error. The message tells you to free a holder or pass an explicit port via the flag (e.g. --port / --proxy-port).","triggerScenarios":"Calling `wmill dev` or `wmill proxy` (which call resolveBindPort) when the requested port and all MAX_SHIFT-1 fallback ports are already bound by other processes.","commonSituations":"A previous wmill dev/proxy instance still running in another terminal or leaked after a crash; another service (Docker, webpack, another dev server) squatting on the default ports; multiple worktrees/instances started on the same machine; a launch.json entry pinned to a specific busy port.","solutions":["Find and stop the holder: `lsof -i :<port>` or `ss -ltnp | grep <port>`, then kill the stale process","Pass a different explicit port, e.g. `wmill dev --port 8001` or the flag named in the error message","Restart Docker/other dev services that are squatting on the port range","Reboot or clear zombie processes if many ports in the range are leaked"],"exampleFix":"// before\n$ wmill dev            # port 8000-... all busy\n// after\n$ wmill dev --port 8123","handlingStrategy":"fallback","validationCode":"import { createServer } from \"net\";\nfunction isPortFree(port: number): Promise<boolean> {\n  return new Promise((res) => {\n    const s = createServer();\n    s.once(\"error\", () => res(false));\n    s.once(\"listening\", () => s.close(() => res(true)));\n    s.listen(port);\n  });\n}\nif (!(await isPortFree(8000))) console.warn(\"port 8000 busy — pass an explicit --port\");","typeGuard":"null","tryCatchPattern":"try {\n  await wmillDev({});\n} catch (e) {\n  if (String(e.message).includes(\"Could not find a free port\")) {\n    await wmillDev({ port: 8123 }); // fallback port\n  } else throw e;\n}","preventionTips":["Before starting dev servers, check `lsof -i :<port>` for stale holders and kill them","Configure an explicit stable port in launch.json so probing never wanders","Clean up background wmill dev/proxy processes after each session","Avoid running multiple worktrees/instances with the same default ports simultaneously"],"tags":["cli","network","port-conflict","dev-server"],"backgroundTag":"port-already-in-use","analyzedSha":"e474e8803ce2ff5c2df09a58dab51d45f5c922ca","analyzedAt":"2026-09-03T12:38:19.024Z","contentChangedAt":"2026-09-03T12:38:19.024Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}