​
Troubleshooting Guide: R2R API Endpoints Not Responding

When R2R API endpoints fail to respond, it can disrupt your entire workflow. This guide will help you diagnose and resolve issues related to unresponsive API endpoints.

​
1. Verify API Service Status

First, ensure that the R2R API service is running: 
docker ps | grep r2r
Look for a container with “r2r” in its name and check its status.

​
2. Check API Logs

Examine the logs of the R2R API container: 
docker logs <r2r-container-id>
Look for error messages or exceptions that might indicate why the API is not responding.

​
3. Common Issues and Solutions

​
3.1 Network Connectivity

Symptom: Unable to reach the API from outside the Docker network. Solutions:
  • Verify port mappings in your Docker Compose file.
  • Ensure the host firewall isn’t blocking the API port.
  • Check if the API is bound to the correct network interface (0.0.0.0 for all interfaces).

​
3.2 Dependencies Not Ready

Symptom: API starts but immediately exits or fails to initialize. Solutions:
  • Verify that all required services (Postgres, etc.) are up and healthy.
  • Check if the depends_on conditions in the Docker Compose file are correct.
  • Increase the retry count or add a delay in the API service startup script.

​
3.3 Configuration Errors

Symptom: API logs show configuration-related errors. Solutions:
  • Double-check environment variables in the Docker Compose file.
  • Verify that the config file (if used) is correctly mounted and accessible.
  • Ensure all required configuration parameters are set.

​
3.4 Resource Constraints

Symptom: API becomes unresponsive under load or fails to start due to lack of resources. Solutions:
  • Check Docker host resources (CPU, memory, disk space).
  • Adjust resource limits in Docker Compose file if necessary.
  • Consider scaling the API service or upgrading the host machine.

​
3.5 Database Connection Issues

Symptom: API logs show database connection errors. Solutions:
  • Verify database credentials and connection strings.
  • Check if the database service is running and accessible.
  • Ensure the database is initialized with the correct schema.

​
3.6 Hatchet Integration Problems

Symptom: API fails to communicate with Hatchet service. Solutions:
  • Verify Hatchet service is running and healthy.
  • Check Hatchet API key and configuration.
  • Ensure network connectivity between R2R and Hatchet services.

​
4. API-specific Debugging Steps

  1. Test individual endpoints: Use tools like cURL or Postman to test specific endpoints and isolate the problem. 
    curl http://localhost:7272/v2/health
  2. Check API documentation: Verify that you’re using the correct endpoint URLs and request formats.
  3. Monitor API metrics: If available, check API metrics for response times, error rates, and request volumes.
  4. Verify API versioning: Ensure you’re using the correct API version in your requests.

​
5. Advanced Troubleshooting

​
5.1 Network Debugging

Use network debugging tools to diagnose connectivity issues: 
docker network inspect r2r-network

​
5.2 Interactive Debugging

Access the R2R container interactively to run diagnostics: 
docker exec -it <r2r-container-id> /bin/bash

​
5.3 API Server Logs

If the API uses a separate web server (e.g., uvicorn), check its logs: 
docker exec <r2r-container-id> cat /path/to/uvicorn.log

​
6. Preventive Measures

  1. Implement robust health checks in your Docker Compose file.
  2. Use logging and monitoring tools to proactively detect issues.
  3. Implement circuit breakers and fallback mechanisms in your application.
  4. Regularly update R2R and its dependencies to the latest stable versions.

​
7. Seeking Help

If you’re still experiencing issues:
  1. Gather all relevant logs, configurations, and error messages.
  2. Check the R2R documentation and GitHub issues for similar problems.
  3. Reach out to the R2R community on Discord or GitHub for support.
  4. When reporting an issue, provide:
    • R2R version
    • Docker and Docker Compose versions
    • Host OS and version
    • Detailed description of the problem and steps to reproduce
    • Relevant logs and configuration files (with sensitive information redacted)
By following this guide, you should be able to diagnose and resolve most issues with unresponsive R2R API endpoints. Remember to approach the problem systematically and gather as much information as possible before seeking external help.