Troubleshooting
This guide covers common issues you might encounter when using b and their solutions.
Installation Issues
Permission Denied
Problem: Getting permission denied errors during installation.
Solution:
# Make sure you have write permissions to the installation directory
# https://github.com/fentas/b/releases/latest/download/install.sh
sudo curl -sSL https://get.binary.help | bash
# Or install to a user directory
# https://github.com/fentas/b/releases/latest/download/install.sh
curl -sSL https://get.binary.help | bash -s -- --prefix=$HOME/.local
Command Not Found
Problem: b: command not found after installation.
Solution:
Configuration Issues
.bin/b.yaml Not Found
Problem: configuration file not found
Solution:
Invalid Configuration
Problem: YAML parsing errors in .bin/b.yaml
Solution:
b.lock Cannot Be Read
Problem: A command stops with cannot read b.lock
b.lock is there, but b cannot read it: it is not valid JSON (for example,
after a merge conflict), or it is not a file. Each command that reads
b.lock stops with this error before it downloads or writes anything:
install, update, list, version, verify, env status, env remove
and env resolve. list and version read b.lock only when b.yaml has
envs. A missing b.lock is not an error: b writes one at the first install.
Solution: Repair b.lock, or remove it. Without b.lock, b downloads
each pinned binary once and writes a new b.lock.
Binary Installation Issues
Download Failures
Problem: Failed to download binary from GitHub releases
b retries a download that fails with a network error, HTTP 429 or HTTP 5xx
(other than 501). It makes up to 5 tries, waits up to 150 seconds in total, and
obeys a Retry-After header. An error that names the URL and the last status
comes after the last try. An error names a URL without its user info, query
and fragment, because they can hold a credential. Other 4xx statuses fail at
once. A try that gets no
response headers in 30 seconds, or no data for 60 seconds, is also retried. A
slow download that continues to receive data is not stopped.
If a server or proxy often pauses a download for more than 60 seconds, set
B_DOWNLOAD_IDLE_TIMEOUT to a longer time. The value is a duration (90s,
5m) or a number of seconds (120). An invalid value, zero or a negative
value gives the default of 60 seconds. The maximum is 24 hours.
A download that fails does not change the installed binary. b writes the new
binary to a temp file in the same directory. It replaces the old binary only
when the download is complete. When a download fails, b install and
b update stop with an error that names each binary whose download failed
(exit code 1). With --add, b install does not change b.yaml.
Because b replaces the binary with a new file:
- The directory of the binary must be writable. When the binary is a symlink, b replaces the file that the link points to, so the directory of that file must be writable. A symlink whose target is missing, or links that make a loop, stop the install with an error.
- The new binary belongs to the user who runs b, with the mode
0755. - A hard link to the old binary keeps the old content.
b writes b.lock in the same way. The new b.lock keeps the mode of the old
one.
When b stops during a download (Ctrl-C, a kill, a crash), its temp file can
stay: a hidden .<name>.<number>.tmp file beside the binary. The next
b install or b update of that binary removes it and names it.
b removes only regular files with exactly that name, and only when no other
b process writes to them. b update --dry-run removes nothing, and b verify
ignores these files. On platforms other than Linux, macOS, the BSDs and
Windows, b leaves them.
Solutions:
# Check your internet connection
curl -I https://github.com
# Check GitHub API rate limits
curl -H "Accept: application/vnd.github.v3+json" https://api.github.com/rate_limit
# If you are using a proxy, make sure your shell environment is configured correctly
# (e.g., HTTP_PROXY, HTTPS_PROXY environment variables).
Archive or Binary Refused
Problem: b install or b update refuses the archive of a binary, or the
binary itself
b checks the file that it takes from an archive (a tar.gz, a tar.xz or a zip) before that file replaces the binary. When a check fails, the old binary stays and the error names the archive and its files:
- The file must not be empty, and it must have the size that the archive header gives.
- Only a regular file can be the binary. A symlink, a directory or a device in a zip archive is never installed.
- An archive that holds a regular file with an absolute name (
/tool), a drive name (C:\tool) or a..element (../tool) is refused. - A file matches the binary when its name without the directory is the name
of the binary (a preset of a tar archive can also give the file name). The
file matches with or without an execute bit: b installs the binary with mode
0755. - When more than one file matches, the one match with an execute bit is the
binary, but only when b knows that every other match has no execute bit.
So
bin/toolinstalls beside a completion scriptcompletions/bash/tool. An archive in which two or more matches have an execute bit, or none has one, is refused. A file in a zip archive has a known mode only when the zip gives it a Unix mode with permission bits (a zip made on Linux or macOS). A match without a known mode can be the real binary, so an archive with such a match beside the binary is refused too. The error gives the number of matches with an execute bit, and with an unknown mode. - The binary must be the only match with its path. An archive that holds the
same path twice (
toolandtool, ortooland./tool) is refused, whatever the modes: an unpack keeps only one of the two files. - When no file matches, b takes the largest candidate of a release asset: a file with an execute bit, or any regular file of a zip archive without Unix modes. Two largest candidates of the same size refuse the archive.
- A tar archive can go on over several gzip members, but one xz stream must hold all of it. After the tar archive, b reads that gzip member or xz stream to its end and checks its checksum. b does not read the bytes after it.
b installs a binary of at most 2 GiB (2147483648 bytes) from a download of at
most 2 GiB. A larger binary or download is refused: by its size when the
archive header or the Content-Length gives one, else while b reads it. A tar
archive that unpacks to more than 8 GiB, and an archive with more than 100000
entries, are refused too. There is no setting for these limits.
Solution: an archive that b refuses does not change when you try again. Read the file names in the error, and report the archive to the project that publishes it.
Version Not Found
Problem: Specified version doesn't exist
Solution:
Binary Not Executable
Problem: Installed binary is not executable
Solution:
PATH and Environment Issues
Tools Not Available
Problem: Installed tools are not available in PATH
Solution:
Conflicting Versions
Problem: System version conflicts with b-managed version
Solution:
Performance Issues
Slow Downloads
Problem: Binary downloads are very slow
Solutions:
Large Git Cache
Problem: b's git cache directory is taking up too much space
Solution:
Env File Sync Issues
Clone Failures
Problem: git clone or git fetch fails when syncing env files
Solutions:
Merge Conflicts
Problem: b update --strategy=merge reports conflicts
Solution:
Env Destination Conflicts
Problem: Two env entries write to the same destination file
Solution:
Verify Mismatches
Problem: b verify reports sha256 mismatches
Solutions:
CI/CD Issues
GitHub Actions Failures
Problem: b installation fails in GitHub Actions
Solution:
Docker Container Issues
Problem: b doesn't work properly in Docker containers
Solution:
Getting Help
If you're still experiencing issues:
- Check the logs: Run commands with
--verboseflag for detailed output - Search existing issues: Check GitHub Issues
- Create a new issue: Include your OS, b version, and error messages
- Join the community: Participate in discussions and get help from other users
Debug Information
When reporting issues, include this information: