gastownhall/beads · error

%d artifact(s) could not be removed

Error message

%d artifact(s) could not be removed

What it means

ClassicArtifacts walks a repo tree for .beads directories and deletes legacy artifacts (stale JSONL exports, SQLite WAL/SHM files, backup DBs, cruft files in redirect-only .beads dirs). It continues past individual removal failures, counting them, and at the end returns this aggregated error reporting how many artifacts could not be removed. It is a batch-cleanup result error, not a single-failure error — the per-item causes are only visible in the 'errors' count of the summary line, and skipped (not deleted) items are reported separately and do not trigger it.

Source

Thrown at cmd/bd/doctor/fix/artifacts.go:54

		removed += r
		skipped += s
		errCount += e

		return filepath.SkipDir
	})
	if err != nil {
		return fmt.Errorf("failed to walk directory tree: %w", err)
	}

	// Report summary
	fmt.Printf("  Artifact cleanup: %d removed, %d skipped, %d errors\n", removed, skipped, errCount)

	if skipped > 0 {
		fmt.Println("  Skipped items may need manual review (e.g., issues.jsonl in dolt dirs, beads.db files)")
	}

	if errCount > 0 {
		return fmt.Errorf("%d artifact(s) could not be removed", errCount)
	}

	return nil
}

// cleanBeadsDirArtifacts cleans artifacts from a single .beads directory.
// Returns counts of removed, skipped, and errored items.
func cleanBeadsDirArtifacts(beadsDir string) (removed, skipped, errCount int) {
	hasDolt := hasDoltDir(beadsDir)
	isRedirectExpected := isRedirectExpectedLocation(beadsDir)

	// 1. Clean JSONL artifacts in dolt-native directories
	if hasDolt {
		r, s, e := cleanJSONLArtifacts(beadsDir)
		removed += r
		skipped += s
		errCount += e
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Stop all running bd processes/daemons that could hold .beads files open, then rerun `bd doctor --fix` (or fix.ClassicArtifacts).
2. Check permissions and ownership of the reported .beads directories; chown/chmod so the current user can delete the files, or run with sufficient privileges.
3. Inspect each .beads directory named in the summary for files that cannot be deleted (immutable flag on Linux: chattr -i; locked handles on Windows) and remove them manually.
4. If artifacts live on a read-only or immutable CI checkout, run the fix in a writable workspace instead.
5. Rerun the cleanup and confirm the summary reports 0 errors.

Example fix

// before
err := fix.ClassicArtifacts(".") // fails while bd daemon holds beads.db-wal

// after
// 1. stop the daemon (or `bd daemon stop`), then:
if err := fix.ClassicArtifacts("."); err != nil {
	fmt.Printf("some artifacts need manual cleanup: %v\n", err)
	os.Exit(1)
}

// Pre-flight: ensure no live bd process holds .beads files and dirs are writable
lsof +D .beads 2>/dev/null && echo "bd files in use — stop bd first"
test -w .beads || echo ".beads not writable by current user"

func canClean(beadsDir string) bool {
	entries, err := os.ReadDir(beadsDir)
	if err != nil {
		return false
	}
	for _, e := range entries {
		if err := unix.Access(filepath.Join(beadsDir, e.Name()), unix.W_OK); err != nil {
			return false
		}
	}
	return true
}

if err := fix.ClassicArtifacts(path); err != nil {
	// summary line above already listed per-item failures
	fmt.Fprintf(os.Stderr, "artifact cleanup incomplete (%v) — remove remaining files manually", err)
}

When it happens

Trigger: Calling fix.ClassicArtifacts(path) when one or more artifact files it tries to delete cannot be removed — e.g. os.Remove fails due to file permissions, read-only filesystem, a file locked by a running process (a live bd process holding beads.db-wal open), or a cruft-file removal failing inside cleanCruftBeadsDirFiles in an expected-redirect .beads directory.

Common situations: Running `bd doctor --fix` on a repo while a bd daemon or another bd process still has SQLite WAL/SHM files open; cleaning a .beads directory owned by another user or checked out with restrictive permissions; running on a read-only mount or CI workspace with artifact files made immutable; Windows file locking on beads.db-wal.

Related errors

• dolt path is not executable
• failed to create backup directory: %w
• failed to create temp file: %w
• failed to create backup file: %w
• failed to walk directory tree: %w

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