What causes "failed to create backup file: %w" in gastownhall/beads?

Create the parent directory first (mkdir -p) or correct a typo in the backup path.

failed to create backup file: %w

Error message

failed to create backup file: %w

What it means

backupPollutedIssues creates the backup file with os.Create at the user-supplied path before writing polluted issues as JSONL. If the file cannot be created — bad directory, permission denied, path is a directory, or disk errors — this wrapped error is returned and the pollution check aborts without backing up.

Source

Thrown at cmd/bd/detect_pollution.go:104

		// Only include if score is above threshold
		if score >= 0.7 {
			results = append(results, pollutionResult{
				issue:   issue,
				score:   score,
				reasons: reasons,
			})
		}
	}

	return results
}

func backupPollutedIssues(polluted []pollutionResult, path string) error {
	// Create backup file
	// nolint:gosec // G304: path is provided by user as explicit backup location
	file, err := os.Create(path)
	if err != nil {
		return fmt.Errorf("failed to create backup file: %w", err)
	}
	defer file.Close()

	// Write each issue as JSONL
	for _, p := range polluted {
		data, err := json.Marshal(p.issue)
		if err != nil {
			return fmt.Errorf("failed to marshal issue %s: %w", p.issue.ID, err)
		}

		if _, err := file.WriteString(string(data) + "\n"); err != nil {
			return fmt.Errorf("failed to write issue %s: %w", p.issue.ID, err)
		}
	}

	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

Create the parent directory first (mkdir -p) or correct a typo in the backup path.
Check write permissions on the target directory (ls -ld) and choose a writable location.
Ensure the path points to a file, not an existing directory.
Re-run the pollution check after fixing the path.

Example fix

// before
bd pollution-check --backup missing-dir/backup.jsonl
// after
mkdir -p missing-dir && bd pollution-check --backup missing-dir/backup.jsonl

Defensive patterns

Strategy: validation

Validate before calling

dir := filepath.Dir(backupPath)
if st, err := os.Stat(dir); err != nil || !st.IsDir() {
    return fmt.Errorf("backup directory %q does not exist", dir)
}
if err := os.WriteFile(filepath.Join(dir, ".probe"), nil, 0o644); err != nil {
    return fmt.Errorf("directory %q not writable: %w", dir, err)
}
os.Remove(filepath.Join(dir, ".probe"))

Try / catch

if err := backupPollutedIssues(polluted, path); err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) && errors.Is(pe.Err, syscall.ENOENT) {
        os.MkdirAll(filepath.Dir(path), 0o755)
        err = backupPollutedIssues(polluted, path)
    }
    if err != nil { return err }
}

Prevention

mkdir -p the backup directory before running pollution checks.
Use absolute, simple file paths for --backup arguments.
Verify write permission on the target directory beforehand.
Never point --backup at an existing directory.

When it happens

Trigger: Running the pollution check with a --backup (or similar) path whose parent directory does not exist, which lacks write permission, or which is itself a directory, causing os.Create to fail.

Common situations: Typo in the backup path (e.g. missing directory); read-only filesystem or restricted $HOME; backing up into a path owned by root; passing a directory instead of a file path.

Related errors

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