Troubleshooting
Use this guide to diagnose and fix common installation and runtime issues.
Quick Diagnostics
If something isn't working, run these commands first to identify the root cause.
| Command | Purpose |
|---|---|
biogrids-cli check-connection |
Verify network access to BioGrids servers. |
biogrids-cli diag |
Run comprehensive system and permission checks. |
biogrids-cli verify |
Check for missing or corrupted software versions. |
Common Issues
1. Permissions & Directories
Problem: Permission Denied
Occurs when creating /opt/biogrids or the /programs symlink without enough privileges.
Solutions:
* Use Sudo: Ensure you have administrative rights for the initial setup.
* Custom Path: Install to a directory you own (e.g., ~/biogrids) using the --target flag:
2. Network & Connectivity
Problem: Downloads Fail or Timeout
BioGrids requires outbound access on several ports.
Checklist: * [ ] Port 443 (HTTPS): Primary API and download port. * [ ] Port 873 (rsync): Required for software synchronization. * [ ] Proxy: If you use a proxy, export these variables before running the CLI:
3. macOS Specifics
Problem: Command Not Found
On macOS Catalina and later, you must reboot after creating the /programs path via synthetic.conf.
Manual Symlink Fix:
# Verify the config exists
cat /etc/synthetic.conf
# Expected output: programs /opt/biogrids (separated by a TAB)
4. Software Not in PATH
Problem: Software is installed but command is not found
BioGrids is not initialized in your current shell.
Solution:
Advanced Troubleshooting
Log Analysis
Check the logs for specific error messages or stack traces:
# View recent installation activity
tail -f ~/.biogrids/logs/installation.log
# Search for errors in all logs
grep -i "error" ~/.biogrids/logs/*.log
Still Need Help?
If you can't resolve the issue using this guide, please contact our technical team:
Please include:
1. The output of uname -a.
2. The output of biogrids-cli diag.
3. Any relevant log snippets from ~/.biogrids/logs/.