{"record":{"id":"16545ad289a421de","repo":"gastownhall/beads","slug":"cannot-create-shared-dolt-directory-s-w","errorCode":null,"errorMessage":"cannot create shared dolt directory %s: %w","messagePattern":"cannot create shared dolt directory (.+?): %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":282,"sourceCode":"\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tif err := os.MkdirAll(dir, config.BeadsDirPerm); err != nil {\n\t\treturn \"\", fmt.Errorf(\"cannot create shared server directory %s: %w\", dir, err)\n\t}\n\treturn dir, nil\n}\n\n// SharedDoltDir returns the dolt data directory for the shared server.\n// Returns ~/.beads/shared-server/dolt/ (created on first use).\nfunc SharedDoltDir() (string, error) {\n\tserverDir, err := SharedServerDir()\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tdir := filepath.Join(serverDir, \"dolt\")\n\tif err := os.MkdirAll(dir, config.BeadsDirPerm); err != nil {\n\t\treturn \"\", fmt.Errorf(\"cannot create shared dolt directory %s: %w\", dir, err)\n\t}\n\treturn dir, nil\n}\n\n// resolveServerDir returns the canonical server directory for dolt state files.\n// In shared server mode, returns ~/.beads/shared-server/ instead of the\n// project's .beads/ directory.\nfunc resolveServerDir(beadsDir string) string {\n\tif IsSharedServerMode() {\n\t\tdir, err := SharedServerDir()\n\t\tif err != nil {\n\t\t\tfmt.Fprintf(os.Stderr, \"Warning: shared server directory unavailable, using per-project mode: %v\\n\", err)\n\t\t\treturn beadsDir\n\t\t}\n\t\treturn dir\n\t}\n\treturn beadsDir\n}","sourceCodeStart":264,"sourceCodeEnd":300,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L264-L300","documentation":"SharedDoltDir returns ~/.beads/shared-server/dolt/, creating it on first use. It first calls SharedServerDir() (propagating its errors untouched) and then os.MkdirAll on the dolt subdirectory; failure to create that subdirectory is wrapped with this message including the full path.","triggerScenarios":"Calling SharedDoltDir() (directly or via ResolveDoltDir/TestSharedDoltDir) when the shared server dir was created but the dolt/ subdir cannot be created — filesystem permission changes between the two calls, a file named dolt inside ~/.beads/shared-server, or ENOSPC/readonly fs.","commonSituations":"Concurrent provisioning where another process created a dolt file instead of a directory, running bd as different users against the same shared HOME, disk quota exhaustion on the shared server volume.","solutions":["Read the wrapped OS error to identify the root cause","Check that ~/.beads/shared-server is a directory and writable","If ~/.beads/shared-server/dolt is a file, remove it so MkdirAll can create the directory","Fix ownership/permissions on the shared-server directory","Free disk space or remount the volume read-write"],"exampleFix":"// before: ignoring error\ndir, _ := doltserver.SharedDoltDir()\n// after: surface the wrapped OS error\ndir, err := doltserver.SharedDoltDir()\nif err != nil {\n    return fmt.Errorf(\"cannot use shared dolt dir: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"serverDir, err := doltserver.SharedServerDir()\nif err == nil {\n    if fi, err := os.Stat(filepath.Join(serverDir, \"dolt\")); err == nil && !fi.IsDir() {\n        return fmt.Errorf(\"%s/dolt is a file; remove it\", serverDir)\n    }\n}","typeGuard":"func isSharedDoltDirErr(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"cannot create shared dolt directory\")\n}","tryCatchPattern":"dir, err := doltserver.SharedDoltDir()\nif err != nil {\n    if strings.Contains(err.Error(), \"not a directory\") || strings.Contains(err.Error(), \"permission denied\") {\n        os.RemoveAll(filepath.Join(serverDirGuess, \"dolt\")) // careful: only if known-bad\n    }\n    return err\n}","preventionTips":["Verify ~/.beads/shared-server is writable before shared-server mode deployments","Watch disk quota on the volume holding ~/.beads","Run all bd instances for a shared HOME under the same user","Treat ENOSPC alerts on the HOME volume as bd-outage alerts"],"tags":["filesystem","mkdir","permissions","shared-server"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}