Skip to main content
Skip to main content

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:

# Add b to your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or for zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Configuration Issues​

.bin/b.yaml Not Found​

Problem: configuration file not found

Solution:

# Initialize b in your project directory
cd your-project
b init

# Or create .bin/b.yaml manually
mkdir -p .bin
cat > .bin/b.yaml << EOF
binaries: {}
EOF

Invalid Configuration​

Problem: YAML parsing errors in .bin/b.yaml

Solution:

# Validate your YAML syntax
# Check for proper indentation and structure
cat .bin/b.yaml

# Example valid format:
binaries:
jq:
version: "1.7"
kubectl:
version: "1.28.0"

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.

export B_DOWNLOAD_IDLE_TIMEOUT=5m
b install

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/tool installs beside a completion script completions/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 (tool and tool, or tool and ./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:

# Search for available versions
b search jq

# Use 'latest' for the most recent version
b install jq@latest

# Check the project's GitHub releases page

Binary Not Executable​

Problem: Installed binary is not executable

Solution:

# Check binary permissions
ls -la ~/.local/share/b/bin/

# Make executable if needed
chmod +x ~/.local/share/b/bin/jq

# Reinstall the binary
b install --force jq

PATH and Environment Issues​

Tools Not Available​

Problem: Installed tools are not available in PATH

Solution:

# Check if b's bin directory is in PATH
echo $PATH | grep -o '[^:]*b[^:]*'

# Source your shell configuration
source ~/.bashrc # or ~/.zshrc

# Check b's configuration
b list

Conflicting Versions​

Problem: System version conflicts with b-managed version

Solution:

# Check which version is being used
which jq
jq --version

# Ensure b's bin directory comes first in PATH
export PATH="$HOME/.local/share/b/bin:$PATH"

# Update your shell configuration
echo 'export PATH="$HOME/.local/share/b/bin:$PATH"' >> ~/.bashrc

Performance Issues​

Slow Downloads​

Problem: Binary downloads are very slow

Solutions:

# Use a different mirror or CDN if available
# Check your network connection
speedtest-cli

# Try downloading during off-peak hours
# Consider using a VPN if geographical restrictions apply

Large Git Cache​

Problem: b's git cache directory is taking up too much space

Solution:

# Check cache location and size
b cache path
du -sh $(b cache path)

# Clean the cache
b cache clean

Env File Sync Issues​

Clone Failures​

Problem: git clone or git fetch fails when syncing env files

Solutions:

# Check connectivity to the remote
git ls-remote https://github.com/org/repo

# Clean the cache and retry
b cache clean
b update

# Ensure git is installed and SSH keys / credentials are configured

Merge Conflicts​

Problem: b update --strategy=merge reports conflicts

Solution:

# Conflicts are marked with standard conflict markers in the file
# Open the conflicting file and resolve manually, then re-run:
b update

# Or use 'replace' to overwrite local changes
b update --strategy=replace

# Or use 'client' to keep your local version
b update --strategy=client

Env Destination Conflicts​

Problem: Two env entries write to the same destination file

Solution:

# Use distinct 'dest' values in b.yaml to avoid overlap
envs:
github.com/org/infra:
files:
manifests/base/**:
dest: infra-base/
github.com/org/overrides:
files:
override/**:
dest: override-base/

Verify Mismatches​

Problem: b verify reports sha256 mismatches

Solutions:

# Check what changed locally
b verify

# Re-sync to restore upstream state
b update --strategy=replace

# Or if you want to keep local changes, update the lock
b update --strategy=client

CI/CD Issues​

GitHub Actions Failures​

Problem: b installation fails in GitHub Actions

Solution:

# Use specific version and add error handling
steps:
- name: Install b
run: |
curl -sSL https://get.binary.help | bash
echo "$HOME/.local/bin" >> $GITHUB_PATH

- name: Verify b installation
run: b version

- name: Install project tools
run: b install

Docker Container Issues​

Problem: b doesn't work properly in Docker containers

Solution:

# Install b in Dockerfile
RUN curl -sSL https://get.binary.help | bash
ENV PATH="/root/.local/bin:$PATH"

# Or use multi-stage build
FROM alpine AS b-installer
RUN apk add --no-cache curl
RUN curl -sSL https://get.binary.help | bash

FROM alpine
COPY --from=b-installer /root/.local/bin/b /usr/local/bin/b

Getting Help​

If you're still experiencing issues:

  1. Check the logs: Run commands with --verbose flag for detailed output
  2. Search existing issues: Check GitHub Issues
  3. Create a new issue: Include your OS, b version, and error messages
  4. Join the community: Participate in discussions and get help from other users

Debug Information​

When reporting issues, include this information:

# b CLI version
b version

# Operating system
uname -a

# Shell information
echo $SHELL
echo $PATH

# Configuration
cat .bin/b.yaml

# Installed binaries
b list
Was this section helpful?