​

Troubleshooting Guide: Neo4j Graph Database Query Failures in R2R

When working with R2R (RAG to Riches) and encountering Neo4j graph database query failures, it’s important to systematically identify and resolve the issues. This guide will help you troubleshoot common problems.

​

1. Verify Neo4j Connection

First, ensure that R2R can connect to Neo4j:

1. Check Neo4j connection settings in your R2R configuration:

   cat /path/to/your/r2r_config.toml
   

   Look for the [graph_store] section and verify the Neo4j URL, username, and password.

2. Try connecting to Neo4j using the official Neo4j Browser or cypher-shell:

   cypher-shell -a bolt://localhost:7687 -u neo4j -p your_password
   

   If this fails, it’s likely a connection issue rather than a query problem.

​

2. Check Neo4j Logs

Neo4j logs can provide valuable information about query failures:

1. Locate Neo4j logs:

   docker exec -it r2r-neo4j-1 bash
   cat /logs/neo4j.log | grep ERROR
   

2. Look for specific error messages related to your queries.

​

3. Validate Cypher Queries

Ensure your Cypher queries are correctly formatted:

1. Extract the failing query from R2R logs:

   docker logs r2r-r2r-1 | grep "Cypher query"
   

2. Test the query directly in Neo4j Browser or cypher-shell.

3. Common Cypher syntax issues:

   • Missing or mismatched parentheses
   • Incorrect property names
   • Case sensitivity (Neo4j is case-sensitive)
   • Incorrect relationship types

​

4. Check for Data Integrity

Ensure the data in Neo4j matches what your queries expect:

1. Verify node labels:

   MATCH (n) RETURN DISTINCT labels(n)
   

2. Check relationship types:

   MATCH ()-[r]->() RETURN DISTINCT type(r)
   

3. Inspect property keys:

   MATCH (n)
   UNWIND keys(n) AS key
   RETURN DISTINCT key
   

​

5. Performance Issues

If queries are failing due to timeouts:

1. Check Neo4j’s query timeout setting:

   docker exec -it r2r-neo4j-1 bash
   cat /var/lib/neo4j/conf/neo4j.conf | grep dbms.transaction.timeout
   

2. Analyze query performance:

   • Use PROFILE before your Cypher query in Neo4j Browser to see execution plans.
   • Look for full graph scans or high-cost operations.

3. Ensure proper indexes are in place:

   SHOW INDEXES
   

​

6. Memory and Resource Constraints

Graph queries can be memory-intensive:

1. Check Neo4j’s memory settings:

   docker exec -it r2r-neo4j-1 bash
   cat /var/lib/neo4j/conf/neo4j.conf | grep dbms.memory
   

2. Monitor Neo4j’s memory usage:

   docker stats r2r-neo4j-1
   

3. Adjust memory settings if necessary in your Docker Compose file.

​

7. Version Compatibility

Ensure R2R is compatible with your Neo4j version:

1. Check Neo4j version:

   docker exec -it r2r-neo4j-1 neo4j --version
   

2. Verify R2R’s supported Neo4j versions in the documentation.

​

8. Plugin Issues

If using Neo4j plugins like APOC or GDS:

1. Verify plugin installation:

   CALL dbms.procedures() YIELD name
   WHERE name STARTS WITH "apoc" OR name STARTS WITH "gds"
   RETURN name
   

2. Check plugin compatibility with your Neo4j version.

​

9. Authentication and Authorization

Ensure the Neo4j user has proper permissions:

1. Check user roles:

   SHOW USERS
   

2. Verify database access rights:

   SHOW USER neo4j PRIVILEGES
   

​

10. Network Issues

For dockerized setups:

1. Ensure Neo4j is on the same Docker network as R2R:

   docker network inspect r2r-network
   

2. Check if Neo4j is accessible from the R2R container:

   docker exec -it r2r-r2r-1 ping neo4j
   

​

Debugging Steps

1. Enable verbose logging in R2R for Neo4j operations.
2. Use Neo4j’s query logging feature to capture all executed queries.
3. Implement query parameter logging in R2R to ensure correct parameter passing.

​

Getting Help

If issues persist:

1. Gather relevant logs (R2R, Neo4j, Docker).
2. Document the exact steps to reproduce the issue.
3. Check R2R and Neo4j documentation for known issues.
4. Consult the R2R community on Discord or GitHub for support.
5. For Neo4j-specific issues, consider posting on Neo4j’s community forums.

Remember to sanitize any sensitive information before sharing logs or queries publicly.

By following this guide, you should be able to identify and resolve most Neo4j query failures in your R2R setup. If problems persist, don’t hesitate to seek help from the R2R or Neo4j communities.