Skip to content

Installation Troubleshooting

This guide covers common BioGrids installation issues and provides diagnostic tools to resolve problems quickly.

Quick Diagnostics

Network Connectivity Test

Use the built-in connectivity checker to verify network access:

biogrids-cli check-connection

Example output: 

info: (1/1) Checking connection...
info: Checking services...
info: Checking sync.biogrids.org (port: 8080) ...
info: Checking sync.biogrids.org (port: 873) ...
info: Checking biogrids.org (HTTPS) ...
info: Checking biogrids.org (HTTP) ...
info: Connectivity test succeeded, all remote services are reachable

System Diagnostics

Run comprehensive diagnostic tests:

biogrids-cli diag

This command checks: - Installation directory permissions - Environment configuration - Network connectivity - Software integrity - Configuration file validity

Configuration Verification

Check for missing or corrupted configuration files:

biogrids-cli verify

This reports: - Missing software versions - Corrupted configuration files - Environment setup issues - Permission problems

Common Installation Issues

Account and Authentication Problems

Invalid Credentials

Problem: "Authentication failed" or "Invalid credentials" errors

Solutions: 1. Verify credentials: Double-check site, username, and activation key 2. Check account status: Ensure BioGrids consortium membership is active 3. Contact support: Email help@biogrids.org for account verification

Example: 

# Verify account with correct format
biogrids-cli activate harvard_bio123 jsmith 3NHMCPpGreyJi48v0DaeYjH6l5duRNyO

Expired Activation Keys

Problem: "Activation key expired" messages

Solutions: 1. Request new key: Log into biogrids.org to generate new credentials 2. Update account: Use account migration if switching between institutions

Permission and Directory Issues

Insufficient Privileges

Problem: "Permission denied" when creating /opt/biogrids or /programs

Solutions: 1. Use sudo: Ensure account has sudo privileges for initial setup 2. Alternative installation: Use --no-link and --target options 3. Custom directory: Install to user-writable location

Examples: 

# Install without sudo to custom location
biogrids-cli activate site user key --no-link --target ~/biogrids

# Create symlink manually later (with sudo)
sudo ln -sf ~/biogrids /programs

Directory Already Exists

Problem: "/opt/biogrids already exists" errors

Solutions: 1. Skip checking: Use --skip-folder-checking flag 2. Remove existing: Delete old installation if safe to do so 3. Use different location: Specify alternative installation directory

# Overwrite existing installation
biogrids-cli activate site user key --skip-folder-checking

macOS-Specific Issues

Gatekeeper and Quarantine

Problem: "App can't be opened because it is from an unidentified developer"

Solutions: 

# Remove quarantine attribute
xattr -d com.apple.quarantine biogrids-cli

# Or download using curl (avoids quarantine)
curl -k -LO https://biogrids.org/downloads/latest/biogrids-cli_macos.tar.gz

Problem: Software not found after installation on macOS Catalina+

Solutions: 1. Check synthetic.conf: Verify /etc/synthetic.conf exists 2. Reboot required: System restart needed after creating synthetic.conf 3. Manual creation: Create the file manually if automatic creation failed

# Verify synthetic.conf exists and is correct
cat /etc/synthetic.conf
# Should show: programs<TAB>/opt/biogrids

# Create manually if missing (requires reboot after)
echo -e "programs\t/opt/biogrids" | sudo tee /etc/synthetic.conf

Rosetta 2 Required (Apple Silicon)

Problem: "Bad CPU type in executable" on M1/M2/M3 Macs

Solutions: 

# Install Rosetta 2 for Intel compatibility
sudo softwareupdate --install-rosetta --agree-to-license

# Verify installation
/usr/bin/pgrep oahd

Network and Connectivity Issues

Firewall and Proxy Problems

Problem: Downloads fail or timeout

Required ports: - HTTPS (443): Primary download protocol - HTTP (80): Fallback protocol
- Port 8080: Alternative download port - Port 873: rsync protocol

Solutions: 1. Check connectivity: Test specific ports 2. Configure proxy: Set proxy environment variables 3. Request firewall changes: Contact IT to open required ports

# Test specific ports
telnet biogrids.org 443
telnet biogrids.org 8080
telnet biogrids.org 873

# Configure proxy
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
biogrids-cli install <software>

DNS Resolution Issues

Problem: "Host not found" or DNS errors

Solutions: 

# Test DNS resolution
nslookup biogrids.org
dig biogrids.org

# Try alternative DNS servers
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

Corporate Network Restrictions

Problem: Downloads blocked by corporate security

Solutions: 1. Work with IT: Request access to biogrids.org domains 2. Use proxy: Configure appropriate proxy settings 3. Alternative download: Use different network if available

Software Installation Failures

Insufficient Disk Space

Problem: "No space left on device" errors

Solutions: 

# Check available space
df -h /opt/biogrids
df -h /tmp

# Clean up if needed
biogrids-cli clean  # Remove obsolete packages
rm -rf /tmp/biogrids_*  # Clear temporary files

# Use different location with more space
biogrids-cli activate site user key --target /large/disk/biogrids

Corrupted Downloads

Problem: Installation fails with checksum errors

Solutions: 

# Clear download cache
rm -rf ~/.biogrids/cache/*

# Retry installation
biogrids-cli install <software> --reinstall

# Use different mirror (if available)
biogrids-cli config set mirror-server backup.biogrids.org

Dependency Resolution Failures

Problem: "Dependency conflict" or "Cannot resolve dependencies"

Solutions: 

# Update package metadata
biogrids-cli update-metadata

# Install dependencies manually
biogrids-cli info <software>  # Check required dependencies
biogrids-cli install <dependency1> <dependency2>

# Force reinstallation
biogrids-cli install <software> --reinstall

Environment Configuration Issues

Software Not Found in PATH

Problem: Installed software not available at command line

Solutions: 

# Verify BioGrids environment is sourced
echo $BIOGRIDS_ROOT
ls -la /programs

# Source environment manually
source /programs/biogrids.shrc

# Add to shell profile for automatic loading
echo 'source /programs/biogrids.shrc' >> ~/.bashrc  # or ~/.zshrc

Version Conflicts

Problem: Wrong software version being used

Solutions: 

# Check installed versions
biogrids-cli list <software> --all-versions

# Configure version preference in ~/.biogrids.conf
echo "BLAST_X=2.12.0" >> ~/.biogrids.conf

# Rebuild environment
biogrids-cli rebuild

Shell Integration Issues

Problem: BioGrids doesn't work with specific shells

Solutions: 

# For zsh users (macOS default)
source /programs/biogrids.shrc

# For tcsh users
source /programs/biogrids.cshrc

# For fish shell users
bash -c 'source /programs/biogrids.shrc; exec fish'

Advanced Troubleshooting

Log File Analysis

Installation Logs

# View recent installation logs
tail -f ~/.biogrids/logs/installation.log

# Search for specific errors
grep -i error ~/.biogrids/logs/*.log
grep -i failed ~/.biogrids/logs/*.log

Network Logs

# Check network-related errors
grep -i "connection" ~/.biogrids/logs/network.log
grep -i "timeout" ~/.biogrids/logs/network.log

Configuration File Debugging

Check Configuration Files

# Main configuration
cat ~/.biogrids/config.json

# Environment configuration  
cat ~/.biogrids/environment.conf

# Version overrides
cat ~/.biogrids.conf

Reset Configuration

# Backup current configuration
cp -r ~/.biogrids ~/.biogrids.backup

# Reset to defaults
rm -rf ~/.biogrids
biogrids-cli activate site user key  # Re-activate

Multi-Platform Installation Issues

Cross-Platform Software Management

# Install software for different platforms
biogrids-cli install blast --linux    # Linux version on macOS system
biogrids-cli install blast --darwin   # macOS version on Linux system

# List platform-specific software
biogrids-cli list --linux
biogrids-cli list --darwin

Performance Optimization

Improving Download Speeds

# Use multiple parallel downloads
biogrids-cli install <software> -j 8

# Configure download cache
biogrids-cli config set cache-size 10GB
biogrids-cli config set parallel-downloads 4

Reducing Disk Usage

# Remove obsolete software versions
biogrids-cli clean

# Install only needed software versions
biogrids-cli install <software>  # Default version only
# Instead of: biogrids-cli install <software> --all-versions

Getting Additional Help

Collecting Diagnostic Information

When contacting support, include:

# System information
uname -a
biogrids-cli --version

# BioGrids configuration
biogrids-cli config list
cat ~/.biogrids/config.json

# Network connectivity
biogrids-cli check-connection

# Recent logs
tail -50 ~/.biogrids/logs/installation.log

Support Channels

Bug Reports

When reporting bugs, include: 1. Exact error messages (copy and paste) 2. Steps to reproduce the issue 3. System information (OS, version, architecture) 4. Log files from the time of the error 5. BioGrids configuration (remove sensitive information)

Emergency Workarounds

If critical for immediate work:

# Bypass network issues with manual download
curl -L -o software.tar.gz https://biogrids.org/manual/software.tar.gz
# Extract and install manually (contact support for instructions)

# Use alternative installation location
biogrids-cli activate site user key --target /tmp/biogrids_emergency

# Use GUI installation manager as alternative
# Download from: https://biogrids.org/downloads/

Remember: Most installation issues can be resolved by checking network connectivity, verifying permissions, and ensuring proper account setup. When in doubt, run the diagnostic commands first to identify the root cause.