Dependencies

R2R Troubleshooting Guide: Dependency Conflicts

Dependency conflicts can occur when different components of the R2R system require incompatible versions of the same library or when there are conflicts between system-level dependencies. This guide will help you identify and resolve common dependency issues.

1. Identifying Dependency Conflicts

Symptoms:

  • Error messages mentioning version conflicts
  • Unexpected behavior in specific components
  • Installation or startup failures

Common Error Messages:

  • “ImportError: cannot import name X from Y"
  • "AttributeError: module X has no attribute Y"
  • "ModuleNotFoundError: No module named X”

2. Python Package Conflicts

2.1 Diagnosing the Issue

  1. Check your Python environment:

    $python --version
    >pip list

  2. Look for conflicting versions in the pip list output.

  3. Use pip check to identify dependency conflicts:

    $pip check

2.2 Resolving Python Package Conflicts

  1. Update R2R and its dependencies:

    $pip install --upgrade r2r[core]

  2. Use a virtual environment:

    $python -m venv r2r_env
    >source r2r_env/bin/activate  # On Windows, use r2r_env\Scripts\activate
    >pip install r2r[core]

  3. Manually resolve conflicts:

    • Identify the conflicting packages
    • Upgrade or downgrade specific packages: 
      $pip install package_name==specific_version

  4. Use pip-compile for deterministic builds:

    $pip install pip-tools
    >pip-compile requirements.in
    >pip-sync requirements.txt

3. System-level Dependency Conflicts

3.1 Diagnosing System Conflicts

  1. Check system library versions:

    $ldd --version
    >ldconfig -p | grep library_name

  2. Look for error messages related to shared libraries:

    • “error while loading shared libraries"
    • "symbol lookup error”

3.2 Resolving System-level Conflicts

  1. Update system packages:

    $sudo apt update && sudo apt upgrade  # For Ubuntu/Debian
    >sudo yum update  # For CentOS/RHEL

  2. Install missing libraries:

    $sudo apt install library_name  # For Ubuntu/Debian
    >sudo yum install library_name  # For CentOS/RHEL

  3. Use container isolation:

    • Consider using Docker to isolate the R2R environment from the host system.

4. Docker-specific Dependency Issues

4.1 Diagnosing Docker Issues

  1. Check Docker image versions:

    $docker images

  2. Inspect Docker logs:

    $docker logs container_name

4.2 Resolving Docker Dependency Conflicts

  1. Update Docker images:

    $docker pull ragtoriches/prod:main-unstructured

  2. Rebuild with no cache:

    $docker-compose build --no-cache

  3. Check Docker Compose file:

    • Ensure all services are using compatible versions
    • Update service versions if necessary

6. Advanced Troubleshooting

6.1 Use Dependency Visualization Tools

  1. Install pipdeptree:

    $pip install pipdeptree

  2. Visualize dependencies:

    $pipdeptree -p r2r

6.2 Analyze Startup Sequences

  1. Use verbose logging:

    $R2R_LOG_LEVEL=DEBUG r2r serve

  2. Analyze logs for import errors or version conflicts

6.3 Temporary Workarounds

  1. Pin problematic dependencies:

    • Create a constraints.txt file with specific versions
    • Install with constraints: 
      $pip install -c constraints.txt r2r[core]

  2. Use compatibility mode:

    • If available, run R2R with a compatibility flag to use older versions of certain components

7. Seeking Further Help

If you’ve tried these steps and still encounter issues:

  1. Check the R2R GitHub Issues for similar problems and solutions
  2. Join the R2R Discord community for real-time support
  3. Open a new issue on GitHub with:
    • Detailed description of the problem
    • Steps to reproduce
    • Environment details (OS, Python version, pip list output)
    • Relevant log snippets

Remember, when dealing with dependency conflicts, it’s crucial to document your changes and test thoroughly after each modification to ensure you haven’t introduced new issues while solving existing ones.