{"record":{"id":"2e4bd0cefeeaf294","repo":"gastownhall/beads","slug":"failed-to-write-readme-md-w","errorCode":null,"errorMessage":"failed to write README.md: %w","messagePattern":"failed to write README\\.md: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/init_templates.go","lineNumber":208,"sourceCode":"- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)\n\n---\n\n*Beads: Issue tracking that moves at the speed of thought* ⚡\n`\n\nfunc createReadme(beadsDir string) error {\n\treadmePath := filepath.Join(beadsDir, \"README.md\")\n\n\t// Skip if already exists\n\tif _, err := os.Stat(readmePath); err == nil {\n\t\treturn nil\n\t}\n\n\t// Write README.md (0644 is standard for markdown files)\n\t// #nosec G306 - README needs to be readable\n\tif err := os.WriteFile(readmePath, []byte(BeadsReadmeTemplate), 0644); err != nil {\n\t\treturn fmt.Errorf(\"failed to write README.md: %w\", err)\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":190,"sourceCodeEnd":213,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/init_templates.go#L190-L213","documentation":"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.","triggerScenarios":"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.","commonSituations":".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.","solutions":["Verify the .beads directory exists and is writable by the current user","Remove/replace anything occupying the README.md path that is not a regular file","Check for read-only mounts or mandatory access-control denials (dmesg/audit log)","Re-run `bd init` after fixing the filesystem condition"],"exampleFix":"// before\n$ bd init\nfailed to write README.md: open /repo/.beads/README.md: is a directory\n// after\n$ rm -rf .beads/README.md   # it was a stray directory\n$ bd init","handlingStrategy":"validation","validationCode":"readmePath := filepath.Join(beadsDir, \"README.md\")\nif fi, err := os.Stat(readmePath); err == nil && fi.IsDir() {\n    return fmt.Errorf(\"README.md path is a directory\")\n}\nif f, err := os.OpenFile(readmePath, os.O_CREATE|os.O_WRONLY, 0644); err != nil {\n    return fmt.Errorf(\"README.md not writable: %w\", err)\n} else { f.Close() }","typeGuard":null,"tryCatchPattern":"if err := createReadme(beadsDir); err != nil {\n    var pe *fs.PathError\n    if errors.As(err, &pe) {\n        log.Printf(\"README write blocked at %s: %v\", pe.Path, pe.Err)\n    }\n    return err\n}","preventionTips":["Keep .beads owned by the user running bd","Do not place directories named README.md under .beads","Check for SELinux/AppArmor denials if writes fail with permission errors","Ensure the workspace is not mounted read-only"],"tags":["filesystem","init","readme","permissions"],"backgroundTag":"file-write-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}