​
Troubleshooting Guide: Incompatible Configuration Settings in R2R

When working with R2R (RAG to Riches), you may encounter issues related to incompatible configuration settings. This guide will help you identify and resolve common configuration conflicts.

​
1. Identifying Configuration Issues

Configuration issues often manifest as error messages during startup or unexpected behavior during runtime. Look for error messages related to configuration in your logs or console output.

​
2. Common Incompatible Configurations

​
2.1 Database Conflicts

Issue: Conflicting database settings between different components. Symptoms:
  • Error messages mentioning database connection failures
  • Inconsistent data retrieval or storage
Resolution:
  1. Check your r2r.toml file for database settings.
  2. Ensure all components (R2R, Hatchet, etc.) use the same database credentials.
  3. Verify that the database URL, port, and name are consistent across all configurations.
Example correction: 
[database]
url = "postgres://user:password@localhost:5432/r2r_db"

​
2.2 LLM Provider Conflicts

Issue: Multiple or incompatible LLM provider settings. Symptoms:
  • Errors about undefined LLM providers
  • Unexpected LLM behavior or responses
Resolution:
  1. Review your LLM provider settings in the configuration.
  2. Ensure only one primary LLM provider is active.
  3. Check that API keys and endpoints are correctly set for the chosen provider.
Example correction: 
[llm_providers]
primary = "openai"
[llm_providers.openai]
api_key = "your-openai-api-key"

​
2.3 Vector Store Misconfigurations

Issue: Incompatible vector store settings. Symptoms:
  • Errors related to vector operations or storage
  • Failure to store or retrieve embeddings
Resolution:
  1. Verify that your chosen vector store (e.g., pgvector) is properly configured.
  2. Ensure the vector store settings match your database configuration.
  3. Check for any conflicting dimension settings in your embeddings configuration.
Example correction: 
[vector_store]
type = "pgvector"
dimension = 1536  # Must match your embedding model's output dimension

​
2.4 Hatchet Orchestration Conflicts

Issue: Misconfigured Hatchet settings leading to orchestration failures. Symptoms:
  • Errors in task queuing or execution
  • Hatchet service failing to start or communicate
Resolution:
  1. Check Hatchet-related environment variables and configuration.
  2. Ensure Hatchet API key and endpoint are correctly set.
  3. Verify RabbitMQ settings if used for task queuing.
Example correction: 
[orchestration]
type = "hatchet"
api_key = "your-hatchet-api-key"
endpoint = "http://localhost:7077"

​
2.5 File Path and Permission Issues

Issue: Incorrect file paths or insufficient permissions. Symptoms:
  • Errors about missing files or directories
  • Permission denied errors when accessing resources
Resolution:
  1. Verify all file paths in your configuration are correct and accessible.
  2. Check permissions on directories used by R2R, especially in Docker environments.
  3. Ensure consistency between host and container paths if using Docker.
Example correction: 
[file_storage]
base_path = "/app/data"  # Ensure this path exists and is writable

​
3. Configuration Validation Steps

  1. Use R2R’s built-in validation: Run r2r validate-config to check for basic configuration errors.
  2. Environment variable check: Ensure all required environment variables are set and not conflicting with configuration file settings.
  3. Docker configuration: If using Docker, verify that your docker-compose.yml file correctly maps volumes and sets environment variables.
  4. Component version compatibility: Ensure all components (R2R, database, vector store, LLM providers) are using compatible versions.

​
4. Advanced Troubleshooting

​
4.1 Configuration Debugging Mode

Enable debug logging to get more detailed information about configuration loading: 
[logging]
level = "DEBUG"

​
4.2 Component Isolation

If you’re unsure which component is causing the issue, try running components in isolation:
  1. Start only the database and vector store.
  2. Add the R2R core service.
  3. Gradually add other services (Hatchet, LLM providers) one by one.
This approach can help identify which specific component or interaction is causing the incompatibility.

​
4.3 Configuration Diff Tool

Use a diff tool to compare your current configuration with a known working configuration or the default template. This can help spot unintended changes or typos.

​
5. Seeking Further Assistance

If you’re still experiencing issues after trying these solutions:
  1. Check the R2R documentation for any recent changes or known issues.
  2. Search the R2R GitHub issues for similar problems and solutions.
  3. Prepare a detailed description of your issue, including:
    • Your full R2R configuration (with sensitive information redacted)
    • Error messages and logs
    • Steps to reproduce the issue
  4. Reach out to the R2R community on Discord or file a GitHub issue with the prepared information.
Remember, when sharing configurations or logs, always remove sensitive information like API keys or passwords. By following this guide, you should be able to identify and resolve most incompatible configuration settings in your R2R setup. If problems persist, don’t hesitate to seek help from the R2R community or support channels.