{"record":{"id":"c8c81f44a386a7bd","repo":"gastownhall/beads","slug":"finding-process-d-w","errorCode":null,"errorMessage":"finding process %d: %w","messagePattern":"finding process (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/doltserver/doltserver_unix.go","lineNumber":142,"sourceCode":"\treturn false\n}\n\n// isProcessAlive checks if a process with the given PID is running.\n// Uses signal 0 which doesn't send a signal but checks process existence.\nfunc isProcessAlive(pid int) bool {\n\tprocess, err := os.FindProcess(pid)\n\tif err != nil {\n\t\treturn false\n\t}\n\treturn process.Signal(syscall.Signal(0)) == nil\n}\n\n// gracefulStop sends SIGTERM, waits for the process to exit, then SIGKILL if needed.\n// Used by reclaimPort and StopWithForce where data has already been flushed.\nfunc gracefulStop(pid int, timeout time.Duration) error {\n\tprocess, err := os.FindProcess(pid)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"finding process %d: %w\", pid, err)\n\t}\n\n\tif err := process.Signal(syscall.SIGTERM); err != nil {\n\t\treturn fmt.Errorf(\"sending SIGTERM to PID %d: %w\", pid, err)\n\t}\n\n\t// Poll for exit\n\tdeadline := time.Now().Add(timeout)\n\tfor time.Now().Before(deadline) {\n\t\ttime.Sleep(500 * time.Millisecond)\n\t\tif process.Signal(syscall.Signal(0)) != nil {\n\t\t\treturn nil // exited\n\t\t}\n\t}\n\n\t// Still running — force kill\n\t_ = process.Signal(syscall.SIGKILL)\n\ttime.Sleep(100 * time.Millisecond)","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver_unix.go#L124-L160","documentation":"gracefulStop wraps the error from os.FindProcess(pid) as \"finding process %d: %w\". os.FindProcess on Unix only fails if the pid is invalid or the OS lookup errors (it does NOT verify the process exists); on Windows it opens a handle and fails if the PID is dead. This library throws it when it cannot obtain a handle to the dolt-server process it is trying to stop gracefully (SIGTERM, then SIGKILL) during reclaimPort or StopWithForce.","triggerScenarios":"Calling gracefulStop (via reclaimPort or StopWithForce) with a pid <= 0 or a stale pid whose process already exited (Windows), or an OS-level failure in process lookup.","commonSituations":"A dolt server recorded in the metadata file died on its own before bd tried to stop it; a recycled/stale PID in stored server metadata; passing a zero or negative PID from a failed earlier parse.","solutions":["Check the pid being passed is the valid, current dolt-server PID from server metadata; re-read metadata in case it is stale.","Treat 'process already done' (os.ErrProcessDone) as success — the goal was a stopped server; retry the port bind instead of failing.","On Unix, verify liveness with signal 0 (process.Signal(syscall.Signal(0))) before assuming the stop failed.","Log and continue: if the process is gone, the port is likely free; proceed with startup."],"exampleFix":"// before\nprocess, err := os.FindProcess(pid)\nif err != nil {\n    return fmt.Errorf(\"finding process %d: %w\", pid, err)\n}\n// after\nprocess, err := os.FindProcess(pid)\nif err != nil {\n    if pid <= 0 {\n        return fmt.Errorf(\"finding process %d: %w\", pid, err)\n    }\n    // already-gone: treat as stopped\n    return nil\n}","handlingStrategy":"try-catch","validationCode":"if pid <= 0 {\n    return fmt.Errorf(\"invalid pid %d; refresh server metadata\", pid)\n}\nif p, err := os.FindProcess(pid); err == nil {\n    if err := p.Signal(syscall.Signal(0)); err != nil {\n        // process already gone; no stop needed\n    }\n}","typeGuard":"func pidLooksAlive(pid int) bool {\n    if pid <= 0 { return false }\n    p, err := os.FindProcess(pid)\n    if err != nil { return false }\n    return p.Signal(syscall.Signal(0)) == nil\n}","tryCatchPattern":"err := gracefulStop(pid, timeout)\nif err != nil {\n    if errors.Is(err, os.ErrProcessDone) {\n        return nil // already stopped\n    }\n    return fmt.Errorf(\"graceful stop pid %d: %w\", pid, err)\n}","preventionTips":["Refresh server metadata before stopping so the PID is current","Probe liveness with signal 0 before issuing SIGTERM","Treat 'process not found' as success when the goal is a stopped server","Run bd as the same user that owns the server process"],"tags":["process","signals","unix","windows","graceful-shutdown"],"backgroundTag":"process-lookup-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}