{"record":{"id":"a807ed73f13bbf3c","repo":"gastownhall/beads","slug":"port-d-is-in-use-by-a-non-dolt-process-pid-d","errorCode":null,"errorMessage":"port %d is in use by a non-dolt process (PID %d).\\n\\n%s\\n\\nFree the port or configure a different one with: bd dolt set port <port>","messagePattern":"port (.+?) is in use by a non-dolt process \\(PID (.+?)\\)\\.\\\\n\\\\n(.+?)\\\\n\\\\nFree the port or configure a different one with: bd dolt set port <port>","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":435,"sourceCode":"\tif isPortAvailable(host, port) {\n\t\treturn 0, nil // port is free\n\t}\n\n\t// Port is busy — find out what's using it\n\tpid := findPIDOnPort(port)\n\tif pid == 0 {\n\t\t// Can't identify the process; port may be in TIME_WAIT or transient use.\n\t\t// Wait briefly and retry.\n\t\ttime.Sleep(2 * time.Second)\n\t\tif isPortAvailable(host, port) {\n\t\t\treturn 0, nil\n\t\t}\n\t\treturn 0, fmt.Errorf(\"port %d is busy but cannot identify the process.\\n\\nCheck with: %s\", port, fmt.Sprintf(portConflictHint, port))\n\t}\n\n\t// Check if it's a dolt sql-server process\n\tif !isDoltProcess(pid) {\n\t\treturn 0, fmt.Errorf(\"port %d is in use by a non-dolt process (PID %d).\\n\\n%s\\n\\nFree the port or configure a different one with: bd dolt set port <port>\", port, pid, portConflictDiagnostics(port))\n\t}\n\n\t// It's a dolt process. Check if it's one we should adopt.\n\n\t// Check if the process is using our data directory (CWD matches our dolt dir).\n\t// dolt sql-server is started with cmd.Dir = doltDir, so CWD is the data dir.\n\tdoltDir := ResolveDoltDir(beadsDir)\n\tif isProcessInDir(pid, doltDir) {\n\t\treturn pid, nil // our server — adopt it\n\t}\n\n\t// Another beads project's Dolt server is on this port.\n\treturn 0, fmt.Errorf(\"port %d is in use by another project's dolt server (PID %d).\\n\\n%s\\n\\nFree the port or use a different one with: bd dolt set port <port>\", port, pid, portConflictDiagnostics(port))\n}\n\n// portConflictDiagnostics returns a multi-line block of operator-actionable\n// hints for diagnosing what's holding a port. Combines the platform-specific\n// listener-discovery command with a docker-in-the-loop hint that frequently","sourceCodeStart":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L417-L453","documentation":"reclaimPort identifies the process holding an explicit port and refuses to proceed if it is not a dolt sql-server. Killing or stealing the port of an unrelated process would be destructive, so bd fails fast with the offending PID and operator diagnostics, advising a port change or freeing the port.","triggerScenarios":"Start() with an explicit port where the port is bound by a non-dolt process (web server, another database, docker-proxy, IDE debugger) — findPIDOnPort returns a PID but isDoltProcess(pid) is false.","commonSituations":"Two projects on one machine hard-coding the same port in config.yaml, a locally running Postgres/MySQL/dev server already on the chosen port, docker publishing a container port onto the same number.","solutions":["Pick another port: bd dolt set port <port>","If the holder is your own Dolt instance (e.g. docker container), don't start a local server — point bd at it: export BEADS_DOLT_SERVER_HOST=127.0.0.1 and BEADS_DOLT_SERVER_PORT=<port>","Stop the conflicting process identified by the PID/diagnostics command","Follow the portConflictDiagnostics block (lsof/ss command) to confirm what is listening"],"exampleFix":"// before: config.yaml pins a port already used by a dev web server\nport: 8080\n// after: choose an unused port\n# bd dolt set port 31145\nport: 31145","handlingStrategy":"validation","validationCode":"// Before configuring an explicit port, ensure nothing non-dolt holds it\nout, _ := exec.Command(\"lsof\", \"-ti\", \":8080\").Output()\nif len(out) > 0 {\n    fmt.Println(\"port 8080 already in use; pick another\")\n}","typeGuard":null,"tryCatchPattern":"_, err := doltserver.Start(beadsDir)\nif err != nil && strings.Contains(err.Error(), \"non-dolt process\") {\n    // switch to a free port programmatically\n    exec.Command(\"bd\", \"dolt\", \"set\", \"port\", \"31145\").Run()\n    _, err = doltserver.Start(beadsDir)\n}","preventionTips":["Assign unique explicit ports per tool/project on a shared machine","If you already run Dolt (docker/systemd), point bd at it instead of pinning the same port","Audit config.yaml and BEADS_DOLT_SERVER_PORT for hardcoded collisions","Run the diagnostics command in the error before killing anything"],"tags":["network","port-conflict","dolt","process"],"backgroundTag":"port-already-in-use","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}