{"record":{"id":"723f555598f00eaf","repo":"gastownhall/beads","slug":"resolve-user-config-yaml-w","errorCode":null,"errorMessage":"resolve user config.yaml: %w","messagePattern":"resolve user config\\.yaml: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/config/user_config_path.go","lineNumber":88,"sourceCode":"func selectUserConfigYamlPath(candidates userConfigYamlCandidates) (string, error) {\n\tif userConfigPathExists(candidates.documented) {\n\t\treturn candidates.documented, nil\n\t}\n\tif candidates.native != candidates.documented && userConfigPathExists(candidates.native) {\n\t\treturn candidates.native, nil\n\t}\n\tif candidates.documented != \"\" {\n\t\treturn candidates.documented, nil\n\t}\n\tif candidates.native != \"\" {\n\t\treturn candidates.native, nil\n\t}\n\n\terr := errors.Join(candidates.homeErr, candidates.nativeErr)\n\tif err == nil {\n\t\terr = errors.New(\"no absolute native user directory is available\")\n\t}\n\treturn \"\", fmt.Errorf(\"resolve user config.yaml: %w\", err)\n}\n\n// UserConfigYamlDisplayPath returns a human-readable location for command\n// output. The tilde form is deliberately confined to this display-only API and\n// must never be passed to a filesystem operation.\nfunc UserConfigYamlDisplayPath() string {\n\treturn userConfigYamlDisplayPath(currentUserConfigYamlCandidates())\n}\n\nfunc userConfigYamlDisplayPath(candidates userConfigYamlCandidates) string {\n\tif path, err := selectUserConfigYamlPath(candidates); err == nil {\n\t\treturn path\n\t}\n\treturn userConfigYamlDisplayFallback\n}\n\nfunc userConfigPathExists(path string) bool {\n\tif path == \"\" {","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/config/user_config_path.go#L70-L106","documentation":"selectUserConfigYamlPath aggregates all candidate-resolution failures (home dir error, native dir error) with errors.Join and wraps them under 'resolve user config.yaml'. It also throws when every candidate resolved but none was an absolute native directory ('no absolute native user directory is available'). It is the top-level wrapper for user-level config.yaml path resolution.","triggerScenarios":"Calling UserConfigYamlPath, userConfigYamlDisplayPath, or any API that resolves the user config when both the home-directory candidate and the native-directory candidate fail — e.g. HOME relative/MSYS-style and USERPROFILE missing or invalid.","commonSituations":"Windows environments under Git Bash/MSYS with mangled HOME; containers running as a user with no HOME set; stripped CI images lacking USERPROFILE.","solutions":["Set HOME to a valid absolute native path (POSIX) or USERPROFILE (Windows), then retry.","Run outside MSYS/Git Bash or unset MSYS-injected HOME overrides.","Ensure the user account has a defined home directory (check `echo $HOME` / `echo %USERPROFILE%`).","Inspect the joined sub-errors in the message to see which candidate (home vs native) failed and fix that root."],"exampleFix":"// before (Dockerfile)\nUSER app\nCMD [\"bd\", \"ready\"]\n// after\nENV HOME=/home/app\nUSER app\nCMD [\"bd\", \"ready\"]","handlingStrategy":"validation","validationCode":"for _, v := range []string{\"HOME\", \"USERPROFILE\"} {\n    if p := os.Getenv(v); p != \"\" && !filepath.IsAbs(p) {\n        return fmt.Errorf(\"%s=%q is not absolute\", v, p)\n    }\n}","typeGuard":"func hasUsableHomeDir() bool {\n    for _, v := range []string{\"HOME\", \"USERPROFILE\"} {\n        if p := os.Getenv(v); p != \"\" && filepath.IsAbs(p) {\n            return true\n        }\n    }\n    return false\n}","tryCatchPattern":"path, err := config.UserConfigYamlPath()\nif err != nil {\n    // err wraps joined candidate sub-errors; surface them for diagnosis\n    return fmt.Errorf(\"fix HOME/USERPROFILE: %w\", err)\n}","preventionTips":["Always define HOME (POSIX) or USERPROFILE (Windows) in containers and CI images.","Set ENV HOME=/home/app in Dockerfiles before switching to a non-root USER.","Avoid launching bd from MSYS/Git Bash with inherited translated paths.","Sanity-check `echo $HOME` before debugging config commands."],"tags":["config","path-resolution","environment"],"backgroundTag":"user-config-resolution-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}