{"record":{"id":"4d5a415dc21a02e7","repo":"gastownhall/beads","slug":"failed-to-create-beads-directory-v-windows-con","errorCode":null,"errorMessage":"failed to create .beads directory: %v\n\nWindows Controlled Folder Access may be blocking bd.exe.\nTo fix: Open Windows Security > Virus & threat protection >\nRansomware protection > Allow an app through Controlled folder access\nand add bd.exe (typically %USERPROFILE%\\go\\bin\\bd.exe).","messagePattern":"failed to create \\.beads directory: (.+?)\n\nWindows Controlled Folder Access may be blocking bd\\.exe\\.\nTo fix: Open Windows Security > Virus & threat protection >\nRansomware protection > Allow an app through Controlled folder access\nand add bd\\.exe \\(typically %USERPROFILE%\\\\go\\\\bin\\\\bd\\.exe\\)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/init.go","lineNumber":1026,"sourceCode":"\t\t\tskipHooks = true\n\t\t}\n\n\t\t// Always create local .beads/ when using default location (CWD/.beads).\n\t\t// The local directory is needed for metadata.json, config.yaml,\n\t\t// .gitignore, and hooks — regardless of where dolt data lives.\n\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 {","sourceCodeStart":1008,"sourceCodeEnd":1044,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/init.go#L1008-L1044","documentation":"When bd init creates the local .beads directory with 0700 permissions and os.MkdirAll returns a permission error, bd gives platform-specific guidance. On Windows, the common cause is Controlled Folder Access (ransomware protection) blocking bd.exe, so the error includes step-by-step remediation.","triggerScenarios":"`bd init` where creating .beads fails with os.IsPermission: on Windows with Controlled Folder Access enabled, or on Unix with unwritable parent directory/root-owned paths.","commonSituations":"Windows Security blocking an unsigned/newly-built bd.exe; running init in a directory owned by another user; CI runners with restricted permissions.","solutions":["On Windows: add bd.exe as an allowed app via Windows Security > Ransomware protection > Controlled folder access","On Unix: fix permissions on the target directory (chown/chmod) or run in a writable location","Run from a directory your user owns, e.g. cd to the project root","If bd.exe is unsigned, sign it or use the released build that Windows trusts"],"exampleFix":"# before (Unix)\nsudo bd init            # creates root-owned dir / permission failures\n# after\ncd /home/user/project && bd init","handlingStrategy":"fallback","validationCode":"mkdir -p .beads || echo \"cannot create .beads: $?)","typeGuard":null,"tryCatchPattern":"if ! mkdir .beads 2>/dev/null; then echo \"check Windows Security Controlled Folder Access for bd.exe\"; fi","preventionTips":["Allow bd.exe in Controlled Folder Access right after installing","Only init in directories your user owns; avoid sudo bd init","On CI, verify runner workspace write permissions before init","Use the signed release build of bd.exe so AV/ransomware protection trusts it"],"tags":["cli","filesystem","permissions","windows"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}