proxy.ForceStopUnverified: refusing to signal pid %d from %s

Error message

proxy.ForceStopUnverified: refusing to signal pid %d from %s: its command line does not reference workspace %s, so it may be an unrelated %s process; stop it manually if it is yours, then quarantine the record by renaming %s to %s.stale-<unix-timestamp> before retrying

What it means

The process IS a bd or dolt binary, but its command line does not mention the current workspace root, so it may belong to a different workspace. ForceStopUnverified refuses to signal it to avoid killing an unrelated bd/dolt process whose PID was recycled into this record. The error names the exact quarantine rename to perform before retrying.

Source

Thrown at internal/storage/dbproxy/proxy/force_stop.go:244

	// dolt be killed; require the command line to tie the process to THIS
	// workspace, and refuse when that scope cannot be established.
	scoped, gone, err := proc.commandLineContains(rootDir)
	if err != nil {
		return fmt.Errorf(
			"proxy.ForceStopUnverified: refusing to signal pid %d from %s: workspace scope could not be established (%v); stop the process manually, then quarantine the record by renaming %s to %s.stale-<unix-timestamp> before retrying",
			pid,
			report.RecordPath,
			err,
			report.RecordPath,
			report.RecordPath,
		)
	}
	if gone {
		report.ProcessWasGone = true
		return nil
	}
	if !scoped {
		return fmt.Errorf(
			"proxy.ForceStopUnverified: refusing to signal pid %d from %s: its command line does not reference workspace %s, so it may be an unrelated %s process; stop it manually if it is yours, then quarantine the record by renaming %s to %s.stale-<unix-timestamp> before retrying",
			pid,
			report.RecordPath,
			rootDir,
			executable,
			report.RecordPath,
			report.RecordPath,
		)
	}

	gone, err = proc.kill()
	if err != nil {
		return fmt.Errorf("proxy.ForceStopUnverified: signal pid %d: %w", pid, err)
	}
	if gone {
		report.ProcessWasGone = true
		return nil
	}

View on GitHub (pinned to 71377f2769)

Solutions

Confirm with ps -p <pid> -o args= whether the process belongs to this workspace; if it is another workspace's daemon, leave it alone
If it is yours and unrelated, stop it manually (kill <pid>)
Quarantine the stale record: rename <record> to <record>.stale-<unix-timestamp>, then retry force-stop
Ensure the daemon for THIS workspace is started in a way that its cmdline includes the workspace root (launch from the workspace directory)

Example fix

// before: blanket-killing the pid
kill -9 $(cat .bd/bd.pid)
// after: verify, quarantine, retry
ps -p $(cat .bd/bd.pid) -o args=
mv .bd/bd.pid .bd/bd.pid.stale-$(date +%s)
bd daemon --force-stop

Defensive patterns

Strategy: validation

Validate before calling

// verify the pid's cmdline belongs to THIS workspace before force-stop
pid := readPidFromRecord(recordPath)
out, _ := exec.Command("ps", "-p", fmt.Sprint(pid), "-o", "args=").Output()
if !strings.Contains(string(out), rootDir) {
    // belongs to another workspace or recycled: quarantine, never kill blindly
    os.Rename(recordPath, recordPath+".stale-"+fmt.Sprint(time.Now().Unix()))
    return nil
}

Type guard

func isForeignWorkspaceErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "does not reference workspace")
}

Prevention

Start each workspace's daemon from its own root directory so argv contains the workspace path
Avoid wrappers/launchers that rewrite argv and drop the workspace path
Use unique workspace directories to reduce cross-workspace PID collisions after restarts
Treat this refusal as a stop-sign: verify with ps before ever killing the PID yourself

When it happens

Trigger: proxy.ForceStopUnverified where the PID now belongs to a bd/dolt process launched from a DIFFERENT workspace directory (PID reuse after the original daemon died), or the daemon was started with a command line that does not include the workspace path (e.g. launched with a relative path from elsewhere or via a wrapper that rewrote argv).

Common situations: Two workspaces on one machine sharing recycled PIDs; daemons started with argv rewritten by containers/wrappers so the root dir string no longer appears in cmdline; snapshot/restored environments where pid files outlive their processes.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/571df02f4796d840. Report an issue: GitHub.