gastownhall/beads · error

proxy.ForceStopUnverified: probe %s: %w

Error message

proxy.ForceStopUnverified: probe %s: %w

What it means

forceStopRecord attempts a non-blocking TryLock on the proxy lock file; if the lock attempt fails with an error other than 'already locked', this error wraps it. The library distinguishes 'lock held by someone' (proceeds to the held-lock force path) from 'lock mechanism itself failed' (this error), since the latter means it cannot safely probe the record.

Source

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

// forceStopRecord runs the inspect-signal-quarantine procedure for one
// process record, writing partial progress into report as it goes.
func forceStopRecord(
	rootDir string,
	lockName string,
	pidName string,
	wantKind string,
	timeout time.Duration,
	report *ForceStopReport,
) error {
	deadline := time.Now().Add(timeout)
	lockPath := filepath.Join(rootDir, lockName)
	lock, err := util.TryLock(lockPath)
	if err == nil {
		defer lock.Unlock()
		return forceStopRecordLocked(rootDir, pidName, wantKind, deadline, report)
	}
	if !lockfile.IsLocked(err) {
		return fmt.Errorf("proxy.ForceStopUnverified: probe %s: %w", lockPath, err)
	}
	report.LockWasHeld = true

	record, err := readForceStopRecord(rootDir, pidName, report)
	if err != nil || record == nil {
		return err
	}
	if err := requireUnverifiableRecord(rootDir, record, wantKind); err != nil {
		return err
	}
	if err := inspectAndStopUnverifiedPID(rootDir, record.Pid, deadline, report); err != nil {
		return err
	}

	lock, err = acquireForceStopLock(lockPath, deadline)
	if err != nil {
		return err
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped cause (%w) for the underlying open/lock syscall error and fix permissions on the lock file and its directory
2. Remove a corrupted or wrongly-typed lock file when no live proxy owns it (verify with ps first)
3. Ensure lockPath points at the intended workspace root, not a stale/moved path
4. Retry once the filesystem is healthy; transient EIO on network filesystems resolves after remount

func lockFileOpenable(path string) error {
    f, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE, 0o644)
    if err != nil {
        return err
    }
    return f.Close()
}

report, err := proxy.ForceStopUnverified(rootDir)
if err != nil && strings.Contains(err.Error(), "probe ") {
    var perr *fs.PathError
    if errors.As(err, &perr) {
        fmt.Fprintf(os.Stderr, "lock file %s: %v\n", perr.Path, perr.Err)
    }
    return err
}

When it happens

Trigger: Calling ForceStopUnverified (via forceStopRecord) when util.TryLock(lockPath) fails with an unexpected error — e.g. the lock file cannot be created/opened due to permissions, the path is a directory, or an I/O error occurs.

Common situations: Lock file path owned by another user, a corrupted lock file, or a workspace directory with restrictive permissions after a backup restore.

Related errors

• proxy.ForceStopUnverified: publish stop epoch: %w
• dolt path is not executable
• failed to create backup directory: %w
• failed to create temp file: %w
• create beads directory: %w

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