{"record":{"id":"5274a397598a8014","repo":"gastownhall/beads","slug":"uow-creating-server-root-directory-w","errorCode":null,"errorMessage":"uow: creating server root directory: %w","messagePattern":"uow: creating server root directory: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/uow/doltserver_provider.go","lineNumber":58,"sourceCode":"\t}\n\tif rootUser == \"\" {\n\t\treturn nil, fmt.Errorf(\"uow: rootUser must not be empty\")\n\t}\n\tif doltBinExec == \"\" {\n\t\treturn nil, fmt.Errorf(\"uow: doltBinExec must not be empty\")\n\t}\n\n\tabsServerRootDir, err := filepath.Abs(serverRootDir)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"uow: resolving server root dir: %w\", err)\n\t}\n\tabsDoltBinExec, err := filepath.Abs(doltBinExec)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"uow: resolving dolt bin exec: %w\", err)\n\t}\n\n\tif err := os.MkdirAll(absServerRootDir, config.BeadsDirPerm); err != nil {\n\t\treturn nil, fmt.Errorf(\"uow: creating server root directory: %w\", err)\n\t}\n\n\tep, err := proxy.GetCreateDatabaseProxyServerEndpoint(absServerRootDir, proxy.OpenOpts{\n\t\tBackend:        backend,\n\t\tConfigFilePath: serverConfigFilePath,\n\t\tLogFilePath:    serverLogFilePath,\n\t\tDoltBinPath:    absDoltBinExec,\n\t\tDatabase:       database,\n\t\tIdleTimeout:    idleTimeout,\n\t\tPort:           proxyPort,\n\t})\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"uow: get proxy endpoint: %w\", err)\n\t}\n\n\treturn openAndInitSchema(ctx, ep, database, rootUser, rootPassword, \"\", teamServer, expectedProjectID, applyProviderOptions(opts))\n}\n","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/doltserver_provider.go#L40-L76","documentation":"os.MkdirAll failed to create (or confirm) the server root directory at the absolutized path, using config.BeadsDirPerm permissions. This typically means a permissions problem on a parent directory, the path exists as a file, or the filesystem is read-only. The OS error is wrapped for detail.","triggerScenarios":"NewDoltServerUOWProvider called with absServerRootDir that cannot be created: parent dir not writable, a file already occupies the path, disk full, or read-only mount.","commonSituations":"Server root under $HOME when HOME is wrong/unwritable (daemons, cron, containers); ~/.beads/beads-data accidentally replaced by a regular file; read-only container filesystem; full disk.","solutions":["Read the wrapped OS error (mkdir ...: permission denied / not a directory / no space) to pinpoint the cause","Ensure the parent directory exists and is writable by the process user","Remove or rename any regular file occupying the server root path","Point serverRootDir at a writable location (e.g. $BEADS_DIR or /var/lib) and check disk space/mount flags"],"exampleFix":"// before\nprov, err := NewDoltServerUOWProvider(ctx, os.TempDir()+\"/beads/locked\", ...) // read-only mount\n// after\nrootDir := filepath.Join(os.Getenv(\"HOME\"), \".beads\", \"dolt\")\nif err := os.MkdirAll(filepath.Dir(rootDir), 0o755); err != nil { return err }\nprov, err := NewDoltServerUOWProvider(ctx, rootDir, ...)","handlingStrategy":"validation","validationCode":"if err := os.MkdirAll(serverRootDir, 0o755); err != nil {\n    return fmt.Errorf(\"server root not creatable before provider init: %w\", err)\n}\n// pre-creating surfaces permission/path issues with a clearer failure point","typeGuard":"func dirCreatable(p string) bool {\n    if fi, err := os.Stat(p); err == nil { return fi.IsDir() }\n    parent := filepath.Dir(p)\n    fi, err := os.Stat(parent)\n    return err == nil && fi.IsDir() && unix.Access(parent, unix.W_OK) == nil\n}","tryCatchPattern":"prov, err := NewDoltServerUOWProvider(...)\nif err != nil {\n    var pe *fs.PathError\n    if errors.As(err, &pe) && strings.Contains(err.Error(), \"creating server root directory\") {\n        return fmt.Errorf(\"check permissions/ownership on %s: %w\", pe.Path, err)\n    }\n    return err\n}","preventionTips":["Pre-create the server root during install/setup, not at runtime","Point serverRootDir at a location writable by the service user (e.g. /var/lib/beads)","Ensure serverRootDir is a directory, not a regular file","Check disk space and mount flags (read-only) in deployment health checks"],"tags":["filesystem","permissions","directory"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}