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
sudo curl -sSL https://github.com/fentas/b/releases/latest/download/install.sh | bash

# Or install to a user directory
curl -sSL https://github.com/fentas/b/releases/latest/download/install.sh | 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 Binary Cache

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

Solution:

# Check cache size
du -sh ~/.local/share/b/

# Manually remove old binaries from the cache.
# Note: A 'b clean' command is planned for a future release.
rm -rf ~/.local/share/b/cache/

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://github.com/fentas/b/releases/latest/download/install.sh | 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://github.com/fentas/b/releases/latest/download/install.sh | 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://github.com/fentas/b/releases/latest/download/install.sh | 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