{"record":{"id":"977e11ba89265406","repo":"oven-sh/bun","slug":"missing-global-bin-directory-try-setting-bun-ins","errorCode":null,"errorMessage":"Missing global bin directory: try setting $BUN_INSTALL","messagePattern":"Missing global bin directory: try setting \\$BUN_INSTALL","errorType":"exception","errorClass":"bun_install::Error","httpStatus":null,"severity":"error","filePath":"src/install/error.rs","lineNumber":145,"sourceCode":"    #[error(\"InvalidAdvisoryFormat\")]\n    InvalidAdvisoryFormat,\n    #[error(\"MissingPackageField\")]\n    MissingPackageField,\n    #[error(\"InvalidPackageField\")]\n    InvalidPackageField,\n    #[error(\"EmptyPackageField\")]\n    EmptyPackageField,\n    #[error(\"InvalidDescriptionField\")]\n    InvalidDescriptionField,\n    #[error(\"InvalidUrlField\")]\n    InvalidUrlField,\n    #[error(\"MissingLevelField\")]\n    MissingLevelField,\n    #[error(\"InvalidLevelField\")]\n    InvalidLevelField,\n    #[error(\"InvalidLevelValue\")]\n    InvalidLevelValue,\n    #[error(\"Missing global bin directory: try setting $BUN_INSTALL\")]\n    MissingGlobalBinDirectoryTrySettingBUNINSTALL,\n    #[error(\"InvalidURL\")]\n    InvalidURL,\n    #[error(\"Fail\")]\n    Fail,\n    #[error(\"IntegrityCheckFailed\")]\n    IntegrityCheckFailed,\n    #[error(\"RepositoryNotFound\")]\n    RepositoryNotFound,\n    #[error(\"DebugTextLockfileRoundTrip\")]\n    DebugTextLockfileRoundTrip,\n    #[error(\"NoPackage\")]\n    NoPackage,\n    #[error(\"BrokenPipe\")]\n    BrokenPipe,\n    #[error(\"WriteFailed\")]\n    WriteFailed,\n    #[error(\"InvalidCharacter\")]","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/oven-sh/bun/blob/8c5296ac459e8252d3cd702f3fbcbb0c249d95d5/src/install/error.rs#L127-L163","documentation":"`bun add -g` (or any command needing the global bin directory) could not determine where to place global binaries (PackageManagerOptions.rs:350-391). Bun checks in order: $BUN_INSTALL_BIN, the global_bin_dir option, $BUN_INSTALL/bin, then $XDG_CACHE_HOME or $HOME + /.bun/bin; when every source is missing the install aborts with this error.","triggerScenarios":"Running a global install (`bun add -g <pkg>`) in an environment where HOME, XDG_CACHE_HOME, BUN_INSTALL, and BUN_INSTALL_BIN are all unset — typically a minimal Docker container, a service account with no home directory, or a CI job that scrubs env vars.","commonSituations":"Docker `scratch`/distroless-ish images with an empty environment; systemd services with restricted env; CI runners unsetting HOME; k8s exec into a container as a UID with no passwd entry.","solutions":["Set BUN_INSTALL to a writable path: export BUN_INSTALL=/usr/local (binaries land in /usr/local/bin)","Or set HOME to a writable directory so ~/.bun/bin is used","Or pass the directory explicitly via --bin-dir (equivalent to the global_bin_dir fallback)","In Dockerfiles, add ENV BUN_INSTALL=/usr/local before global installs"],"exampleFix":"# before (Dockerfile)\nRUN bun add -g prisma   # fails: no HOME, no BUN_INSTALL\n\n# after\nENV BUN_INSTALL=/usr/local\nRUN bun add -g prisma","handlingStrategy":"validation","validationCode":"# before bun add -g, ensure a bin dir source exists\n[ -n \"$BUN_INSTALL\" ] || [ -n \"$BUN_INSTALL_BIN\" ] || [ -n \"$HOME\" ] || [ -n \"$XDG_CACHE_HOME\" ] || { echo 'set BUN_INSTALL (or HOME) for global installs' >&2; exit 1; }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set ENV BUN_INSTALL=/usr/local in Dockerfiles that use global installs","For service accounts/systemd units, set BUN_INSTALL explicitly since HOME may be unset","Pass --bin-dir when you need a specific destination without relying on env"],"tags":["global-install","environment-variables","docker","ci"],"backgroundTag":null,"analyzedSha":"8c5296ac459e8252d3cd702f3fbcbb0c249d95d5","analyzedAt":"2026-08-16T08:01:58.794Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}