{"record":{"id":"9eaa291dee64e10e","repo":"gastownhall/beads","slug":"unable-to-determine-home-directory-w","errorCode":null,"errorMessage":"unable to determine home directory: %w","messagePattern":"unable to determine home directory: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/doctor/claude.go","lineNumber":538,"sourceCode":"\t\t\tStatus:  StatusWarning,\n\t\t\tMessage: \"beads plugin not installed\",\n\t\t\tFix:     \"Install plugin: /plugin marketplace add steveyegge/beads && /plugin install beads (see docs/integrations/claude-code-plugin.md)\",\n\t\t}\n\t}\n\n\treturn DoctorCheck{\n\t\tName:    \"Claude Plugin\",\n\t\tStatus:  StatusOK,\n\t\tMessage: fmt.Sprintf(\"version %s (update check skipped in non-interactive mode)\", pluginVersion),\n\t}\n}\n\n// GetClaudePluginVersion returns the installed beads Claude plugin version.\nfunc GetClaudePluginVersion() (version string, installed bool, err error) {\n\t// Get user home directory (cross-platform)\n\thomeDir, err := os.UserHomeDir()\n\tif err != nil {\n\t\treturn \"\", false, fmt.Errorf(\"unable to determine home directory: %w\", err)\n\t}\n\n\t// Path to installed_plugins.json\n\tpluginPath := filepath.Join(homeDir, \".claude\", \"plugins\", \"installed_plugins.json\")\n\n\t// Read plugin file\n\tdata, err := os.ReadFile(pluginPath) // #nosec G304 - path is controlled\n\tif err != nil {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn \"\", false, nil\n\t\t}\n\t\treturn \"\", false, fmt.Errorf(\"unable to read plugin file: %w\", err)\n\t}\n\n\t// First, determine the format version\n\tvar versionCheck struct {\n\t\tVersion int `json:\"version\"`\n\t}","sourceCodeStart":520,"sourceCodeEnd":556,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/doctor/claude.go#L520-L556","documentation":"GetClaudePluginVersion first resolves the user's home directory via os.UserHomeDir; if that fails (no HOME env on Unix, missing user profile on Windows), it wraps the OS error. Without a home directory it cannot locate ~/.claude/plugins/installed_plugins.json to read the beads plugin version.","triggerScenarios":"GetClaudePluginVersion (via CheckClaudePlugin during `bd doctor`) when os.UserHomeDir returns an error — typically $HOME unset/empty on Linux, or the user account lacking a resolvable profile — at cmd/bd/doctor/claude.go:538.","commonSituations":"Running bd in a minimal container or CI job with HOME unset; running under a service account (systemd, cron) without a home dir; Windows accounts without a user profile; sudo/su setups that clear HOME.","solutions":["Set HOME to your real home directory (export HOME=/home/<user>) before running bd","Run bd as a normal user with an existing home directory instead of a system account","In containers/CI, explicitly set HOME in the Dockerfile/pipeline (ENV HOME=/root)","Verify the current user has a valid entry in /etc/passwd (or a Windows profile)"],"exampleFix":"# before (CI step)\n- run: bd doctor\n# after\n- run: |\n    export HOME=/root\n    bd doctor","handlingStrategy":"fallback","validationCode":"import \"os\"\nfunc homeOr(dir string) string {\n\tif h, err := os.UserHomeDir(); err == nil { return h }\n\treturn dir\n}","typeGuard":null,"tryCatchPattern":"_, installed, err := GetClaudePluginVersion()\nif err != nil {\n\tlog.Printf(\"plugin check skipped (no home dir): %v\", err)\n\treturn // treat as not-installed rather than failing doctor\n}","preventionTips":["Always export HOME in containers, CI, cron, and systemd units","Avoid clearing environment variables in sudo/wrappers (use sudo -E when needed)","Verify service accounts have valid home entries in /etc/passwd","Set HOME explicitly in Dockerfiles (ENV HOME=/root)"],"tags":["environment","home-directory","doctor","claude-plugin"],"backgroundTag":"home-directory-not-set","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}