Known Issues

This page documents current limitations, known bugs, and workarounds in BioGrids. We regularly update this list as issues are resolved and new ones are identified.

Installation Issues

Network Connectivity

Issue: Installation fails on networks that block required ports Affected: All platforms Workaround: Request firewall access to ports 443, 8080, and 873, or use proxy configuration Status: Ongoing - working with IT departments for standard port access

macOS Catalina+ Permissions

Issue: /programs symlink creation requires reboot on macOS 10.15+ Affected: macOS Catalina, Big Sur, Monterey, Ventura, Sonoma Workaround: Manual creation of /etc/synthetic.conf and system reboot Status: Cannot fix - macOS security requirement

Apple Silicon Compatibility

Issue: Some legacy software requires Rosetta 2 translation Affected: M1/M2/M3 Mac systems Workaround: Install Rosetta 2 with softwareupdate --install-rosetta Status: Ongoing - migrating to native ARM64 builds

Software-Specific Issues

GPU Software Dependencies

Issue: CUDA version mismatches between software and system drivers Affected: RELION, GROMACS, TensorFlow, PyTorch GPU versions Workaround: Use CPU versions or install compatible CUDA drivers Status: Active development - improving CUDA detection

Java Memory Issues

Issue: Java applications may fail with default memory settings Affected: GATK, IGV, Cytoscape, other Java applications Workaround: Set JAVA_OPTS="-Xmx8g" or appropriate memory limit Status: Investigating automatic memory detection

R Package Dependencies

Issue: Some R packages require system libraries not in base installation Affected: Bioconductor packages, packages with compiled code Workaround: Install system dependencies via package manager Status: Working on dependency documentation

Environment Issues

Shell Integration Problems

Issue: BioGrids environment not loading in some shell configurations Affected: Custom shell setups, some Linux distributions Workaround: Manually source /programs/biogrids.shrc in shell profile Status: Improving shell detection and compatibility

Version Override Precedence

Issue: Unclear version selection when multiple overrides exist Affected: Sites with complex version management Workaround: Use biogrids-info --precedence to check version selection Status: Improving documentation and diagnostic tools

Module System Conflicts

Issue: Conflicts with existing environment module systems Affected: HPC systems with Lmod or Environment Modules Workaround: Load BioGrids before or after modules, use isolation Status: Developing better module integration

Platform-Specific Issues

Linux Distribution Compatibility

Issue: Some software may not work on very new or old Linux distributions Affected: Bleeding-edge or legacy Linux systems Workaround: Use supported distributions (RHEL 7+, Ubuntu 18.04+) Status: Expanding platform support

Network File System Performance

Issue: Slow startup times with some NFS configurations Affected: Sites using NFS for /programs Workaround: Enable NFS caching, use local storage for temporary files Status: Optimizing NFS performance

SELinux Policy Conflicts

Issue: SELinux may block BioGrids software execution Affected: RHEL/CentOS systems with strict SELinux Workaround: Configure appropriate SELinux contexts or use permissive mode Status: Developing SELinux policy guidelines

Cloud Computing Issues

AWS Instance Store Access

Issue: Instance store volumes not automatically configured Affected: AWS instances with NVMe SSD storage Workaround: Manually mount and format instance store volumes Status: Developing automated configuration scripts

Container Runtime Dependencies

Issue: Some containerized workflows require specific runtime configurations Affected: Docker, Singularity container usage Workaround: Use provided container configurations Status: Improving container documentation

Spot Instance Interruptions

Issue: AWS Spot instances may be terminated during long-running jobs Affected: Cost-optimized AWS deployments Workaround: Use checkpointing, mixed instance types, or on-demand instances Status: Developing interruption handling strategies

Performance Issues

Large File Handling

Issue: Performance degradation with very large datasets (>1TB) Affected: Genome assembly, large-scale proteomics Workaround: Use streaming processing, split datasets, optimize storage Status: Investigating I/O optimization strategies

Memory Usage Monitoring

Issue: Insufficient memory monitoring for resource-intensive applications Affected: High-memory applications on shared systems Workaround: Monitor resource usage manually, use system monitoring tools Status: Developing integrated resource monitoring

Parallel Processing Overhead

Issue: Some parallel applications show poor scaling Affected: OpenMP and MPI applications on certain systems Workaround: Adjust thread counts, use optimal processor binding Status: Optimizing parallel application configurations

License and Access Issues

Commercial Software Licensing

Issue: License server connectivity problems Affected: MATLAB, Schrodinger, Gaussian, other commercial software Workaround: Check network connectivity, verify license server configuration Status: Improving license diagnostics and documentation

Consortium Membership Verification

Issue: Delays in membership verification for new users Affected: New BioGrids users and institutions Workaround: Contact help@biogrids.org for expedited processing Status: Streamlining verification process

Workarounds and Solutions

General Troubleshooting Steps

Check system requirements: Verify OS compatibility and prerequisites
Test network connectivity: Use biogrids-cli check-connection
Verify installation integrity: Run biogrids-cli verify
Check logs: Review installation and error logs
Update software: Ensure you're using the latest BioGrids version

Environment Reset Procedure

If experiencing persistent issues:

# Backup current configuration
cp ~/.biogrids.conf ~/.biogrids.conf.backup

# Reset BioGrids environment
biogrids-cli reset --full

# Reinstall if necessary
biogrids-cli reinstall --core

Performance Optimization

For performance issues:

# Enable performance monitoring
biogrids-cli monitor --enable

# Optimize for local system
biogrids-cli optimize --system-specific

# Clear caches
biogrids-cli clear-cache --all

Reporting New Issues

Before Reporting

Check this page for known issues and workarounds
Search documentation for relevant troubleshooting information
Test on minimal case to isolate the problem
Gather system information including OS, version, and error messages

How to Report

Email help@biogrids.org with:

Detailed description of the issue
Steps to reproduce the problem
Error messages (exact text, screenshots if applicable)
System information: OS, BioGrids version, hardware specs
Log files from the time the issue occurred

Information to Include

# Gather system information
uname -a
biogrids-cli --version
biogrids-cli diag --full > biogrids-diagnostic.txt

# Include relevant log files
ls ~/.biogrids/logs/

Planned Fixes and Improvements

Short Term (Next Release)

Enhanced error messages for common installation failures
Improved CUDA version detection and compatibility checking
Better integration with container runtimes
Expanded platform support for newer Linux distributions

Medium Term (Next 6 Months)

Native Apple Silicon builds for more software packages
Advanced resource monitoring and management
Improved cloud deployment automation
Enhanced security and compliance features

Long Term (Future Releases)

Machine learning-based performance optimization
Advanced workflow orchestration capabilities
Expanded multi-cloud support beyond AWS
Next-generation dependency resolution

Community Contributions

Known Issue Tracking

We maintain a public issue tracker where you can: - View reported issues and their status - Contribute workarounds and solutions - Vote on priority of fixes - Track development progress

Contributing Fixes

If you develop a workaround or fix: - Share it with the community via the mailing list - Submit documentation improvements - Contribute code fixes via pull requests - Help other users with similar issues

Status Legend

Fixed: Issue resolved in latest release
In Progress: Actively being worked on
Investigating: Issue confirmed, solution being researched
Workaround Available: Temporary solution provided
Won't Fix: Issue cannot be resolved due to external constraints

For the most current status of these issues, check the BioGrids status page or contact help@biogrids.org.