{"record":{"id":"0fca091e22661647","repo":"gastownhall/beads","slug":"cannot-determine-home-directory-w","errorCode":null,"errorMessage":"cannot determine home directory: %w","messagePattern":"cannot determine home directory: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":254,"sourceCode":"\tif err != nil || secs < 1 {\n\t\tfmt.Fprintf(os.Stderr,\n\t\t\t\"Warning: BEADS_DOLT_READY_TIMEOUT=%q is not a positive integer; using default %s\\n\",\n\t\t\tv, defaultTimeout)\n\t\treturn defaultTimeout\n\t}\n\treturn time.Duration(secs) * time.Second\n}\n\n// SharedServerPath returns the directory for shared server state files without\n// creating it. Override with BEADS_SHARED_SERVER_DIR for testing or custom\n// layouts; otherwise it resolves to ~/.beads/shared-server/.\nfunc SharedServerPath() (string, error) {\n\tif d := os.Getenv(\"BEADS_SHARED_SERVER_DIR\"); d != \"\" {\n\t\treturn d, nil\n\t}\n\thome, err := os.UserHomeDir()\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"cannot determine home directory: %w\", err)\n\t}\n\treturn filepath.Join(home, \".beads\", \"shared-server\"), nil\n}\n\n// SharedServerDir returns the directory for shared server state files.\n// Returns ~/.beads/shared-server/ (created on first use).\n// Override with BEADS_SHARED_SERVER_DIR env var for testing or custom layouts.\nfunc SharedServerDir() (string, error) {\n\tdir, err := SharedServerPath()\n\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","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L236-L272","documentation":"SharedServerPath computes the default shared-server state directory under the user's home (~/.beads/shared-server). If os.UserHomeDir fails (no HOME set, or the OS call errors), the path cannot be determined and this error wraps the cause. BEADS_SHARED_SERVER_DIR overrides the home-derived path entirely.","triggerScenarios":"Calling SharedServerPath (directly or via SharedServerDir/SharedDoltPath) with no BEADS_SHARED_SERVER_DIR set while HOME is unset/empty or unreadable — common in stripped-down service, cron, or container environments.","commonSituations":"Running bd from systemd/cron with a minimal env (no HOME); Docker containers running as a non-root user without HOME; Windows profile-location API failures; CI runners with sanitized environments.","solutions":["Set the BEADS_SHARED_SERVER_DIR environment variable to an explicit writable directory.","Set HOME (and USERPROFILE on Windows) in the service/container environment.","Fix the wrapped %w cause — e.g. point the user's home at an existing directory.","Run the command as a user whose home directory exists and is readable."],"exampleFix":"// before\n# systemd unit without HOME\nExecStart=/usr/local/bin/bd dolt start\n// after\n[Service]\nEnvironment=HOME=/home/bd\nExecStart=/usr/local/bin/bd dolt start","handlingStrategy":"fallback","validationCode":"if os.Getenv(\"BEADS_SHARED_SERVER_DIR\") == \"\" {\n    if _, err := os.UserHomeDir(); err != nil {\n        os.Setenv(\"BEADS_SHARED_SERVER_DIR\", \"/var/lib/beads/shared-server\") // explicit fallback\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set HOME (and USERPROFILE on Windows) in service, cron, and container environments.","Prefer setting BEADS_SHARED_SERVER_DIR explicitly for headless deployments.","Sanity-check `echo $HOME` before running bd in stripped-down shells."],"tags":["environment","home-directory","paths"],"backgroundTag":"missing-home-directory","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}