gastownhall/beads · error

probe recorded pid: %w

Error message

probe recorded pid: %w

What it means

When a backend PID record fails V2 validation, cleanup probes the recorded PID to see if the process is dead or alive. If that probe itself errors (and the PID was not confirmed dead), the probe error is joined with the validation error and surfaced inside an unverifiableProcessError, refusing cleanup because liveness could not be established.

Source

Thrown at internal/storage/dbproxy/proxy/endpoint.go:793

				readErr,
				unverifiableProcessChecks{},
			)
		}
		return fmt.Errorf("read backend record %s: %w", recordPath, readErr)
	}
	if pf == nil {
		return nil
	}
	if err := pf.ValidateV2(pidfile.KindDoltBackend); err != nil {
		dead, live, probeErr := probeUnverifiablePID(pf.Pid)
		if dead {
			if _, quarantineErr := quarantineRecord(rootDir, server.PIDFileName, time.Now()); quarantineErr != nil {
				return fmt.Errorf("quarantine dead unverifiable backend record: %w", quarantineErr)
			}
			return nil
		}
		if probeErr != nil {
			err = errors.Join(err, fmt.Errorf("probe recorded pid: %w", probeErr))
		}
		return unverifiableProcessError(
			"backend cleanup",
			recordPath,
			pf.Pid,
			err,
			unverifiableProcessChecks{
				LiveEstablished: live,
			},
		)
	}
	expectedRootID, err := identity.RootID(rootDir)
	if err != nil {
		return fmt.Errorf("resolve backend root identity: %w", err)
	}
	if pf.RootID != expectedRootID {
		return unverifiableProcessError(
			"backend cleanup",

View on GitHub (pinned to 71377f2769)

Solutions

1. Inspect the record file; fix or remove an invalid pid value (pid must be > 0).
2. Follow the unverifiableProcessError guidance: stop the recorded process with the binary that started it, then quarantine manually: mv <recordPath> <recordPath>.stale-<unix-ts>.
3. Recreate the workspace metadata if the record is from an incompatible legacy version.
4. Retry after confirming no dolt-backend process for this workspace is running.

Example fix

// before (record with pid 0)
Error: backend cleanup refused for unverifiable process pid 0 ...: probe recorded pid: record has no valid pid
// after
$ cat /ws/.beads/dbproxy/dolt-backend.pid  # inspect
$ mv /ws/.beads/dbproxy/dolt-backend.pid /ws/.beads/dbproxy/dolt-backend.pid.stale-$(date +%s)

// Before cleanup, sanity-check the record's pid yourself:
if data, err := os.ReadFile(recordPath); err == nil {
    var rec struct{ Pid int `json:"pid"` }
    if json.Unmarshal(data, &rec) == nil && rec.Pid <= 0 {
        os.Rename(recordPath, recordPath+".stale-"+fmt.Sprint(time.Now().Unix()))
    }
}

func hasValidPID(pf *pidfile.Pidfile) bool { return pf != nil && pf.Pid > 0 }

var ule *unverifiableLifecycleError
if err := cleanupOrphanBackend(rootDir); err != nil {
    if errors.As(err, &ule) {
        // follow guidance: stop recorded process, then mv record to .stale-<ts>
        return nil
    }
    return err
}

When it happens

Trigger: pf.ValidateV2(pidfile.KindDoltBackend) fails AND probeUnverifiablePID(pf.Pid) returns a non-nil error (e.g. pid <= 0 'record has no valid pid', or the OS process-liveness check fails) at internal/storage/dbproxy/proxy/endpoint.go:785-793.

Common situations: A corrupt or hand-edited pidfile with pid 0/negative; an OS API failure while probing (e.g. OpenProcess failure on Windows not implying death); a record written by a very old bd version with an incompatible format.

Related errors

• record has no valid pid
• read backend record %s: %w
• quarantine dead unverifiable backend record: %w
• root identity mismatch (record has %q, workspace has %q)
• quarantine dead backend record: %w

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