gastownhall/beads · error

failed to remove %s: %w

Error message

failed to remove %s: %w

What it means

FixStaleMQFiles deletes the stale message-queue directory with os.RemoveAll after confirming it exists. If RemoveAll fails (it reports the first error encountered while walking/removing), the path and cause are wrapped in this error. It means stale mq cleanup could not complete and stale files remain.

Source

Thrown at cmd/bd/doctor/maintenance.go:303

		Status:   StatusWarning,
		Message:  fmt.Sprintf("%d stale .beads/mq/*.json file(s)", len(files)),
		Detail:   "Legacy orchestrator merge queue files (local only, safe to delete)",
		Fix:      "Run 'bd doctor --fix' to delete, or 'rm -rf .beads/mq/'",
		Category: CategoryMaintenance,
	}
}

// FixStaleMQFiles removes the legacy .beads/mq/ directory and all its contents.
func FixStaleMQFiles(path string) error {
	beadsDir := ResolveBeadsDirForRepo(path)
	mqDir := filepath.Join(beadsDir, "mq")

	if _, err := os.Stat(mqDir); os.IsNotExist(err) {
		return nil // Nothing to do
	}

	if err := os.RemoveAll(mqDir); err != nil {
		return fmt.Errorf("failed to remove %s: %w", mqDir, err)
	}

	return nil
}

// checkMisclassifiedWisps detects wisp-patterned issues that lack the ephemeral flag.
// Issues with IDs containing "-wisp-" should always have Ephemeral=true.
// If they're in the issue store without the ephemeral flag, they'll pollute bd ready.
func checkMisclassifiedWisps(path string) DoctorCheck {
	issues, err := loadMisclassifiedWispIssues(path)
	if err != nil {
		return DoctorCheck{
			Name:     "Misclassified Wisps",
			Status:   StatusOK,
			Message:  maintenanceIssuesUnavailableMessage,
			Category: CategoryMaintenance,
		}
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Fix ownership/permissions on the mq directory: sudo chown -R $(whoami) <mqDir> then retry.
2. Stop other bd processes that may hold files open, then re-run bd doctor --fix.
3. Remove the directory manually if permitted: rm -rf <mqDir>.
4. Check the filesystem is writable (mount rw) and files are not immutable (chattr -i).

Example fix

// before
$ bd doctor --fix
Error: failed to remove /repo/.beads/mq: permission denied
// after
$ sudo chown -R $(whoami) .beads/mq
$ bd doctor --fix
✓ stale mq files removed

if info, err := os.Stat(mqDir); err == nil {
    if err := syscall.Access(mqDir, os.W_OK); err != nil {
        return fmt.Errorf("precheck: mq dir %s not writable: %v", mqDir, err)
    }
}

if err := doctor.FixStaleMQFiles(path); err != nil {
    if strings.Contains(err.Error(), "failed to remove") {
        // fall back to manual cleanup or chown then retry once
    }
    return err
}

When it happens

Trigger: os.RemoveAll(mqDir) returns an error — typically EACCES/EPERM on files or parent dirs inside mqDir, a read-only filesystem, or another process holding an unavoidable lock on Windows.

Common situations: The .beads mq directory is owned by root or another user; a concurrently running bd process recreated/locked files mid-delete; read-only CI filesystem; immutable files left by a crashed process.

Related errors

• failed to walk directory tree: %w
• %d artifact(s) could not be removed
• remove expired quarantine %s: %w
• remove dead spawn marker: %w
• dolt path is not executable

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