​

Troubleshooting Guide: Neo4j Version Compatibility with R2R

Neo4j version compatibility is crucial for the proper functioning of R2R (RAG to Riches). This guide will help you diagnose and resolve issues related to Neo4j versions in your R2R deployment.

​

1. Checking Neo4j Version

First, verify the version of Neo4j you’re running:

1. If using Docker:

   docker exec -it <neo4j-container-name> neo4j --version
   

2. If installed directly on the host:

   neo4j --version
   

​

2. R2R Compatibility Matrix

R2R is generally compatible with Neo4j versions 4.x and 5.x. Here’s a quick compatibility matrix:

• Neo4j 3.x: Not supported
• Neo4j 4.x: Supported (4.4+ recommended)
• Neo4j 5.x: Fully supported and recommended

​

3. Common Issues and Solutions

​

3.1 Outdated Neo4j Version

Symptom: R2R fails to connect to Neo4j or throws deprecation warnings.

Solution:

1. Update Neo4j to the latest supported version:

   • For Docker:

     neo4j:
       image: neo4j:5.21.0  # Or the latest 5.x version
     

   • For direct installation, follow Neo4j’s official upgrade guide.

2. After updating, restart your R2R application.

​

3.2 Incompatible Cypher Queries

Symptom: Some Cypher queries fail or produce unexpected results after a Neo4j version update.

Solution:

1. Review R2R logs for specific Cypher query errors.
2. Consult Neo4j’s changelog for syntax changes between versions.
3. Update the problematic queries in your R2R configuration or custom code.

​

3.3 Plugin Compatibility Issues

Symptom: Neo4j plugins (like APOC or GDS) fail to load or function correctly.

Solution:

1. Ensure plugin versions match your Neo4j version:

   environment:
     - NEO4J_PLUGINS=["apoc", "graph-data-science"]
     - NEO4J_apoc_version=5.21.0  # Should match Neo4j version
     - NEO4J_gds_version=2.5.0  # Choose compatible GDS version
   

2. If using custom plugins, check their compatibility with your Neo4j version.

​

3.4 Connection String Mismatches

Symptom: R2R fails to establish a connection with Neo4j.

Solution:

1. Verify the connection string in R2R configuration:

   [neo4j]
   url = "bolt://neo4j:7687"  # Use "neo4j+s://" for Neo4j 4.x with SSL
   

2. Ensure the protocol (bolt, neo4j, neo4j+s) is correct for your Neo4j version and setup.

​

3.5 Authentication Changes

Symptom: R2R fails to authenticate with Neo4j after an update.

Solution:

1. Check if the authentication method has changed (e.g., from basic auth to JWT in newer versions).
2. Update the R2R configuration to match Neo4j’s current authentication requirements:

   [neo4j]
   user = "neo4j"
   password = "your_password"
   # Add any new authentication parameters here
   

​

4. Debugging Steps

If you’re still experiencing issues:

1. Enable verbose logging in both R2R and Neo4j.
2. Check Neo4j logs for any startup or runtime errors:

   docker logs <neo4j-container-name>
   

3. Verify network connectivity between R2R and Neo4j containers.
4. Try connecting to Neo4j using a standalone tool (like Neo4j Browser) to isolate R2R-specific issues.

​

5. Rollback Procedure

If all else fails, you may need to rollback to a previous working version:

1. Document your current Neo4j version and configuration.
2. Stop the R2R and Neo4j services.
3. Revert to the last known working Neo4j image in your Docker Compose file.
4. Restart the services and verify functionality.

​

6. Seeking Help

If you’re unable to resolve the issue:

1. Gather the following information:
   • R2R version
   • Neo4j version (before and after any updates)
   • Relevant sections of R2R and Neo4j logs
   • Your Docker Compose file (with sensitive information redacted)
2. Check the R2R GitHub Issues for similar problems.
3. If your issue is unique, create a new GitHub issue with the gathered information.

Remember to always backup your data before making significant version changes to your database system.