{"record":{"id":"8cc38f971d0366ce","repo":"gastownhall/beads","slug":"failed-to-create-beads-directory-v","errorCode":null,"errorMessage":"failed to create .beads directory: %v","messagePattern":"failed to create \\.beads directory: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/init.go","lineNumber":1038,"sourceCode":"\n\t\tif useLocalBeads {\n\t\t\t// Create .beads directory with owner-only permissions (0700).\n\t\t\tif err := os.MkdirAll(beadsDir, config.BeadsDirPerm); err != nil {\n\t\t\t\tif os.IsPermission(err) {\n\t\t\t\t\tif runtime.GOOS == \"windows\" {\n\t\t\t\t\t\treturn fmt.Errorf(\"failed to create .beads directory: %v\\n\\n\"+\n\t\t\t\t\t\t\t\"Windows Controlled Folder Access may be blocking bd.exe.\\n\"+\n\t\t\t\t\t\t\t\"To fix: Open Windows Security > Virus & threat protection >\\n\"+\n\t\t\t\t\t\t\t\"Ransomware protection > Allow an app through Controlled folder access\\n\"+\n\t\t\t\t\t\t\t\"and add bd.exe (typically %%USERPROFILE%%\\\\go\\\\bin\\\\bd.exe).\", err)\n\t\t\t\t\t} else {\n\t\t\t\t\t\treturn fmt.Errorf(\"failed to create .beads directory: %v\\n\\n\"+\n\t\t\t\t\t\t\t\"Permission denied. Check directory ownership and permissions:\\n\"+\n\t\t\t\t\t\t\t\"  ls -la %s\\n\"+\n\t\t\t\t\t\t\t\"  chmod 755 %s\", err, filepath.Dir(beadsDir), filepath.Dir(beadsDir))\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn fmt.Errorf(\"failed to create .beads directory: %v\", err)\n\t\t\t}\n\n\t\t\t// Fix permissions on pre-existing .beads/ directories that may\n\t\t\t// have been created with a permissive umask (GH#3391).\n\t\t\tif fixed, err := config.FixBeadsDirPermissions(beadsDir); err != nil {\n\t\t\t\tif !quiet {\n\t\t\t\t\tfmt.Fprintf(os.Stderr, \"Warning: could not fix .beads permissions: %v\\n\", err)\n\t\t\t\t}\n\t\t\t} else if fixed && !quiet {\n\t\t\t\tfmt.Fprintf(os.Stderr, \"Fixed .beads permissions to %04o\\n\", config.BeadsDirPerm)\n\t\t\t}\n\n\t\t\t// On Linux btrfs, disable transparent compression on .beads/ so that\n\t\t\t// dolt's hot append-only write path (under .beads/dolt/ or\n\t\t\t// .beads/embeddeddolt/) does not trigger kworker thrashing from\n\t\t\t// read-modify-write-recompress cycles. New files created inside this\n\t\t\t// directory inherit FS_NOCOW_FL automatically, so setting it here —\n\t\t\t// before dolt writes anything — covers both server and embedded modes.","sourceCodeStart":1020,"sourceCodeEnd":1056,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/init.go#L1020-L1056","documentation":"Generic fallback error when `bd init` fails to create the `.beads/` directory for any reason other than a permission denial (or outside the mapped cases). It surfaces the raw OS error without extra remediation hints.","triggerScenarios":"os.MkdirAll(beadsDir, ...) returns a non-permission error (e.g. ENOSPC, ENOTDIR, EEXIST-as-file, EROFS path variants not classified as permission) during `bd init`.","commonSituations":"Disk full when creating .beads, a regular file named `.beads` already exists in the project, the target path component is not a directory, or a filesystem I/O error.","solutions":["Read the wrapped %v OS error to identify the exact cause","If a file named .beads exists, remove it: rm .beads, then re-run bd init","Free disk space if ENOSPC (df -h)","Verify the path is valid and each component is a directory"],"exampleFix":"// before (fails: .beads is a file)\n$ ls -la; -rw-r--r-- .beads\n// after\n$ rm .beads\n$ bd init","handlingStrategy":"validation","validationCode":"if [ -e .beads ] && [ ! -d .beads ]; then\n  echo \".beads exists but is not a directory\"; rm -f .beads\nfi\ndf -h . | awk 'NR==2{exit ($4+0>1024)?0:1}' || echo \"low disk space\"","typeGuard":null,"tryCatchPattern":"bd init || { echo \"init failed: $(cat err)\"; ls -la .beads 2>/dev/null; }","preventionTips":["Ensure nothing named .beads other than the directory exists","Monitor disk space before provisioning","Run bd init from a clean, valid project path"],"tags":["filesystem","init"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}