gastownhall/beads · error

quarantine dead unverifiable backend record: %w

Error message

quarantine dead unverifiable backend record: %w

What it means

When the backend PID record fails V2 validation (ValidateV2 with KindDoltBackend) but the recorded PID is probed as dead, cleanup tries to quarantine the record by renaming it into the quarantine area. This error wraps a failure of that quarantine rename, meaning a dead/stale record could not be moved out of the way and cleanup aborts.

Source

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

		if isMalformedPIDFileError(readErr) {
			return unverifiableProcessError(
				"backend cleanup",
				recordPath,
				0,
				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 {

View on GitHub (pinned to 71377f2769)

Solutions

1. Check write permissions on the workspace root and quarantine directory and fix them.
2. Manually rename the record: mv <recordPath> <recordPath>.stale-$(date +%s), then retry.
3. Ensure no concurrent bd process is holding or recreating the record; stop other bd instances first.
4. Free disk space or remount the filesystem read-write if the wrapped cause indicates ENOSPC/EROFS.

Example fix

// before
Error: quarantine dead unverifiable backend record: rename ...: permission denied
// after
$ mv /ws/.beads/dbproxy/dolt-backend.pid /ws/.beads/dbproxy/dolt-backend.pid.stale-$(date +%s)
$ bd doctor

qDir := filepath.Join(rootDir, "quarantine")
if err := os.MkdirAll(qDir, 0o755); err != nil {
    return fmt.Errorf("quarantine dir unavailable: %w", err)
}

if err := cleanupOrphanBackend(rootDir); err != nil && strings.Contains(err.Error(), "quarantine dead unverifiable backend record") {
    // fallback: rename the record manually and retry once
    os.Rename(recordPath, recordPath+".stale-"+strconv.FormatInt(time.Now().Unix(), 10))
    err = cleanupOrphanBackend(rootDir)
}

When it happens

Trigger: pf.ValidateV2 fails, probeUnverifiablePID reports dead=true, and quarantineRecord(rootDir, server.PIDFileName, time.Now()) returns an error (rename failed) at internal/storage/dbproxy/proxy/endpoint.go:787-788.

Common situations: Quarantine directory not writable; target quarantine name already exists and rename fails; filesystem is read-only or full; the record was concurrently removed/locked by another bd process.

Related errors

• quarantine orphan backend record: %w
• read backend record %s: %w
• quarantine dead backend record: %w
• proxy.ForceStopUnverified: re-read %s: %w
• write pid file: %w

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