oven-sh/bun · error · bun_install::Error

Missing global bin directory: try setting $BUN_INSTALL

Error message

Missing global bin directory: try setting $BUN_INSTALL

What it means

`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.

Source

Thrown at src/install/error.rs:145

    #[error("InvalidAdvisoryFormat")]
    InvalidAdvisoryFormat,
    #[error("MissingPackageField")]
    MissingPackageField,
    #[error("InvalidPackageField")]
    InvalidPackageField,
    #[error("EmptyPackageField")]
    EmptyPackageField,
    #[error("InvalidDescriptionField")]
    InvalidDescriptionField,
    #[error("InvalidUrlField")]
    InvalidUrlField,
    #[error("MissingLevelField")]
    MissingLevelField,
    #[error("InvalidLevelField")]
    InvalidLevelField,
    #[error("InvalidLevelValue")]
    InvalidLevelValue,
    #[error("Missing global bin directory: try setting $BUN_INSTALL")]
    MissingGlobalBinDirectoryTrySettingBUNINSTALL,
    #[error("InvalidURL")]
    InvalidURL,
    #[error("Fail")]
    Fail,
    #[error("IntegrityCheckFailed")]
    IntegrityCheckFailed,
    #[error("RepositoryNotFound")]
    RepositoryNotFound,
    #[error("DebugTextLockfileRoundTrip")]
    DebugTextLockfileRoundTrip,
    #[error("NoPackage")]
    NoPackage,
    #[error("BrokenPipe")]
    BrokenPipe,
    #[error("WriteFailed")]
    WriteFailed,
    #[error("InvalidCharacter")]

View on GitHub (pinned to 8c5296ac45)

Solutions

1. Set BUN_INSTALL to a writable path: export BUN_INSTALL=/usr/local (binaries land in /usr/local/bin)
2. Or set HOME to a writable directory so ~/.bun/bin is used
3. Or pass the directory explicitly via --bin-dir (equivalent to the global_bin_dir fallback)
4. In Dockerfiles, add ENV BUN_INSTALL=/usr/local before global installs

Example fix

# before (Dockerfile)
RUN bun add -g prisma   # fails: no HOME, no BUN_INSTALL

# after
ENV BUN_INSTALL=/usr/local
RUN bun add -g prisma

# before bun add -g, ensure a bin dir source exists
[ -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; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Missing environment variables
• GITHUB_TOKEN environment variable is required
• Dockerfile not found: ${dockerfilePath}
• BUILDKITE_AGENT_TOKEN not set and no existing buildkite-agen
• Buildkite token not found: set BUILDKITE_AGENT_TOKEN or gran

AI-assisted analysis of oven-sh/bun@8c5296ac45 (2026-08-16). Data as JSON: /api/errors/977e11ba89265406. Report an issue: GitHub.