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"

Binary Installation Issues

Download Failures

Problem: Failed to download binary from GitHub releases

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

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