{"record":{"id":"699fcfa059ab3bfa","repo":"gastownhall/beads","slug":"failed-to-create-beads-directory-v-permission","errorCode":null,"errorMessage":"failed to create .beads directory: %v\n\nPermission denied. Check directory ownership and permissions:\n  ls -la %s\n  chmod 755 %s","messagePattern":"failed to create \\.beads directory: (.+?)\n\nPermission denied\\. Check directory ownership and permissions:\n  ls -la (.+?)\n  chmod 755 (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/init.go","lineNumber":1032,"sourceCode":"\t\t// Only skip when BEADS_DIR explicitly points outside the project.\n\t\t//\n\t\t// Previous logic only created .beads/ when the dolt data dir was a\n\t\t// subdirectory of .beads/, which broke server mode with external\n\t\t// BEADS_DOLT_DATA_DIR or BEADS_DOLT_* env vars (GH#2519).\n\t\tuseLocalBeads := !hasExplicitBeadsDir || filepath.Clean(initDBDirAbs) == filepath.Clean(beadsDirAbs)\n\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","sourceCodeStart":1014,"sourceCodeEnd":1050,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/init.go#L1014-L1050","documentation":"During `bd init`, creating the `.beads/` directory failed with a permission error (os.IsPermission). On non-Windows systems bd wraps the underlying OS error with diagnostics telling the developer to inspect ownership/permissions of the parent directory and chmod 755 it.","triggerScenarios":"os.MkdirAll(beadsDir, ...) returns an os.IsPermission error during `bd init` on a Unix-like system; the err is syscall.EACCES/EPERM writing to the parent directory.","commonSituations":"Running bd init in a directory owned by another user (e.g. a checkout created by root), a read-only mount or NFS export, a project directory inside a system path like /usr, or running bd without write access after switching users or in a restricted CI container.","solutions":["Check ownership/permissions of the parent directory: ls -la <parent-of-.beads>","Fix permissions: chmod 755 <parent> or chown to the current user","Move to a writable directory or run init in the actual project root","If on a read-only mount, remount rw or copy the project to a writable location"],"exampleFix":"// before (fails)\n$ cd /srv/project-owned-by-root && bd init\n// after\n$ sudo chown -R $USER /srv/project\n$ bd init","handlingStrategy":"validation","validationCode":"parent=$(dirname .beads)\nif [ ! -w \"$parent\" ]; then\n  echo \"Cannot write $parent — fix permissions before bd init\"\n  ls -la \"$parent\"; chmod 755 \"$parent\"\nfi","typeGuard":null,"tryCatchPattern":"if err := bd init; case \"$?\" in 0) ;; *) echo \"init failed; check perms on $(pwd)\" ;; esac","preventionTips":["Run bd init as the user who owns the project directory","Never init inside root-owned checkouts without chown first","Verify write access with touch .bd-perm-test before init","Avoid read-only mounts for active projects"],"tags":["filesystem","permissions","init"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}