gastownhall/beads · warning

record has no valid pid

Error message

record has no valid pid

What it means

probeUnverifiablePID refuses to act on a pidfile record whose stored PID is zero or negative. Such a record carries no process identity, so liveness cannot be probed via procid.Capture and force-stop/shutdown logic must not guess. It is a sentinel-style input validation error produced by the cleanup/classification paths (cleanupOrphanBackend, classifyInvalidKillRecord).

Source

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

	if checks.LegacyProxy && checks.LiveEstablished {
		stopGuidance = "stop the pre-upgrade proxy with the old bd binary"
	}
	return &unverifiableLifecycleError{message: fmt.Sprintf(
		"%s refused for unverifiable%s process pid %d recorded at %s: %v; %s, then quarantine the record manually by renaming %s to %s.stale-<unix-timestamp> before retrying",
		operation,
		liveness,
		pid,
		recordPath,
		cause,
		stopGuidance,
		recordPath,
		recordPath,
	)}
}

func probeUnverifiablePID(pid int) (dead bool, live bool, err error) {
	if pid <= 0 {
		return false, false, errors.New("record has no valid pid")
	}
	_, err = procid.Capture(pid)
	if err == nil {
		return false, true, nil
	}
	if procid.IsProcessGone(err) {
		return true, false, nil
	}
	return false, false, err
}

func openRecordedProcess(pf *pidfile.PidFile) (*procid.Handle, bool, error) {
	handle, err := procid.Open(pf.Pid, procid.Token(pf.Birth))
	if err == nil {
		return handle, false, nil
	}
	if procid.IsProcessGone(err) {
		return nil, true, nil

View on GitHub (pinned to 71377f2769)

Solutions

1. Regenerate the PID file by starting the server/daemon so a valid PID is written
2. Delete the invalid PID file and let the proxy recreate it on next start
3. Add a pre-check that pid > 0 before passing records into force-stop/cleanup logic

Example fix

// before
probeUnverifiablePID(record.PID) // pid == 0 -> error
// after
if record.PID <= 0 {
    os.Remove(recordPath) // drop invalid record
    return
}
probeUnverifiablePID(record.PID)

if record.PID <= 0 {
    return fmt.Errorf("skipping record %s: no valid pid", recordPath)
}
dead, live, err := probeUnverifiablePID(record.PID)

When it happens

Trigger: Calling ForceStopUnverified or orphan-cleanup code paths against a PID file whose 'pid' field is <= 0 (corrupted, hand-edited, or legacy/empty record).

Common situations: Corrupted or truncated pidfile after a crash; manually written test pidfiles; legacy record formats missing the pid field.

Related errors

• no store is open for this workspace
• not found
• no absolute native user directory is available
• ExternalDoltConfig: set either Socket OR (Host, Port), not b
• ExternalDoltConfig: must set Socket or (Host, Port)

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