gastownhall/beads · error

failed to write README.md: %w

Error message

failed to write README.md: %w

What it means

createReadme writes the standard .beads/README.md from the embedded BeadsReadmeTemplate using os.WriteFile with mode 0644. If the write fails, the error is wrapped as 'failed to write README.md: %w'. The README documents the .beads directory for teammates; init fails without it.

Source

Thrown at cmd/bd/init_templates.go:208

- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)

---

*Beads: Issue tracking that moves at the speed of thought* ⚡
`

func createReadme(beadsDir string) error {
	readmePath := filepath.Join(beadsDir, "README.md")

	// Skip if already exists
	if _, err := os.Stat(readmePath); err == nil {
		return nil
	}

	// Write README.md (0644 is standard for markdown files)
	// #nosec G306 - README needs to be readable
	if err := os.WriteFile(readmePath, []byte(BeadsReadmeTemplate), 0644); err != nil {
		return fmt.Errorf("failed to write README.md: %w", err)
	}

	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the .beads directory exists and is writable by the current user
2. Remove/replace anything occupying the README.md path that is not a regular file
3. Check for read-only mounts or mandatory access-control denials (dmesg/audit log)
4. Re-run `bd init` after fixing the filesystem condition

Example fix

// before
$ bd init
failed to write README.md: open /repo/.beads/README.md: is a directory
// after
$ rm -rf .beads/README.md   # it was a stray directory
$ bd init

readmePath := filepath.Join(beadsDir, "README.md")
if fi, err := os.Stat(readmePath); err == nil && fi.IsDir() {
    return fmt.Errorf("README.md path is a directory")
}
if f, err := os.OpenFile(readmePath, os.O_CREATE|os.O_WRONLY, 0644); err != nil {
    return fmt.Errorf("README.md not writable: %w", err)
} else { f.Close() }

if err := createReadme(beadsDir); err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) {
        log.Printf("README write blocked at %s: %v", pe.Path, pe.Err)
    }
    return err
}

When it happens

Trigger: Running `bd init` when os.WriteFile on the README path fails: missing parent directory, permission denied, target path is a directory, read-only filesystem, or disk full.

Common situations: .beads owned by another user (e.g., created via sudo earlier); workspace mounted read-only; a directory named README.md exists; SELinux/AppArmor denial on the path.

Related errors

• failed to create .beads directory: %v Permission denied. Ch
• failed to create .beads directory: %w
• failed to set beads.role config: %w
• failed to create %s: %w
• failed to read %s: %w

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