Evolution API V2.3.6: Fixing Redis Connection Issues

by Alex Johnson 53 views

Experiencing issues with Redis connections in Evolution API v2.3.6? You're not alone! This article dives deep into a specific bug reported by users, where Redis connections fail, leading to an infinite disconnect loop or a silent crash. We'll explore the problem, analyze potential causes, and offer solutions to get your Evolution API running smoothly. This comprehensive guide is designed to help you understand and resolve these frustrating Redis connection problems.

Understanding the Redis Connection Bug in Evolution API v2.3.6

The core issue revolves around the Evolution API v2.3.6's inability to establish a stable connection with Redis, a popular in-memory data store used for caching and session management. Users have reported two primary behaviors:

Infinite Disconnect Loop

In this scenario, the Evolution API attempts to connect to Redis but fails repeatedly, resulting in an endless loop of "redis disconnected" errors in the logs. This can quickly flood your logs and consume system resources. The error messages, such as ERROR [Redis] [string] redis disconnected, repeat incessantly, making it difficult to pinpoint the root cause. This behavior typically occurs when all Redis-related environment variables are configured, suggesting the API is actively trying to connect but failing. The constant attempts to reconnect can overwhelm the system, leading to performance degradation.

Silent Crash

Alternatively, the container might crash silently after Prisma migrations are executed successfully. The node dist/main process starts but then halts without any further logs, leaving the Node.js process running but unresponsive. This silent failure is particularly challenging to diagnose, as there are no explicit error messages to guide troubleshooting. This often happens when only some Redis variables are set, indicating a partial configuration that leads to a critical failure during startup. The lack of logs makes it difficult to understand what went wrong, leaving users in the dark about the issue.

This bug, specifically reported in version 2.3.6, highlights a potential issue within the Redis client implementation. It seems there might be a problem in how the API initializes or configures the connection, leading to these persistent connection failures. Understanding these behaviors is the first step in resolving the issue.

Diagnosing the Redis Connection Problem

Before diving into solutions, it's crucial to accurately diagnose the problem. Let's walk through the steps taken by a user who encountered this bug and how they verified their setup.

Initial Setup and Configuration

The user performed a clean installation of Evolution API v2.3.6 using Docker Compose with PostgreSQL and Redis. The setup included defining a bridge network for container communication and configuring environment variables for Redis:

REDIS_ENABLED=true
REDIS_URI=redis://redis:6379
REDIS_PASSWORD=

CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://redis:6379
CACHE_REDIS_PREFIX_KEY=evolution
CACHE_REDIS_TTL=604800

The Docker Compose configuration looked like this:

redis:
  image: redis:7-alpine
  container_name: whatsapp_verbo_redis
  restart: unless-stopped
  healthcheck:
    test: ["CMD", "redis-cli", "ping"]
    interval: 10s
    timeout: 5s
    retries: 5
  ports:
    - "6379:6379"
  networks:
    - verbo_network

evolution-api:
  image: evoapicloud/evolution-api:v2.3.6
  container_name: whatsapp_verbo_evolution
  restart: unless-stopped
  env_file:
    - .env
  ports:
    - "8080:8080"
  networks:
    - verbo_network
  depends_on:
    redis:
      condition: service_healthy

This configuration ensures that the Evolution API container depends on the Redis container and that Redis is healthy before the API attempts to connect. The healthcheck in the Docker Compose file is crucial for ensuring Redis is up and running before the API tries to connect.

Verification Steps

To ensure Redis was functioning correctly, the user performed several checks:

  • Redis Container Status: Confirmed that the Redis container reported a "Healthy" status in docker ps. This indicates that Redis itself is running without issues.
  • Redis Ping Test: Executed docker exec -it whatsapp_verbo_redis redis-cli PING and received a PONG response. This confirms that the Redis server is responsive and accepting connections.
  • Network Connectivity: Verified network connectivity by running ping redis inside the Evolution API container, which was successful. This confirms that the API container can reach the Redis container via the network.
  • PostgreSQL Connection: Confirmed that the API could connect to PostgreSQL normally and execute migrations successfully. This rules out general network or database connectivity issues.

These steps demonstrate a thorough approach to verifying the environment and isolating the problem specifically to the Redis connection within the Evolution API.

Observed Behavior and Temporary Solution

Despite the successful verification steps, the user encountered the two problematic behaviors:

  1. Infinite Loop of Redis Errors: When all Redis variables were configured, the API logged an endless stream of ERROR [Redis] redis disconnected messages.
  2. Silent Crash: When only some Redis variables were set, the API container would crash silently after Prisma migrations, without any error messages.

The temporary solution found was to completely disable Redis by setting:

REDIS_ENABLED=false
CACHE_REDIS_ENABLED=false

With Redis disabled, the API started normally and functioned correctly, including QR code generation, webhook handling, and message sending. This workaround, while effective for basic functionality, highlights the need for a proper solution to leverage Redis for caching and performance optimization. Disabling Redis means the API is running without the benefits of caching, which can impact performance and scalability.

Environment Specifications

To provide a comprehensive understanding of the environment, the user detailed their system specifications:

  • Operating System: Ubuntu Linux (x86_64)
  • Docker: 27.x
  • Docker Compose: v2.x
  • Redis: redis:7-alpine (also tested with redis:6-alpine)
  • PostgreSQL: postgres:15-alpine
  • Network: Custom Docker bridge network

The consistency of the issue across different Redis versions (7-alpine and 6-alpine) suggests that the problem is not specific to a particular Redis version but rather lies within the Evolution API's Redis client implementation.

Log Analysis

The user provided valuable log outputs that further illustrate the problem.

Infinite Disconnect Loop Logs

The logs show the API initializing RedisCache for various groups but then immediately encountering disconnection errors:

[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:17     VERBOSE   [CacheEngine]  [string]  RedisCache initialized for groups 
[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:17     VERBOSE   [CacheService]  [string]  cacheservice created using cache engine: ms 
[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:17     VERBOSE   [CacheEngine]  [string]  RedisCache initialized for instance 
[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:17     VERBOSE   [CacheService]  [string]  cacheservice created using cache engine: ms 
[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:17     VERBOSE   [CacheEngine]  [string]  RedisCache initialized for baileys 
[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:17     VERBOSE   [CacheService]  [string]  cacheservice created using cache engine: ms 
[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:17     INFO   [WA MODULE]  [string]  Module - ON 
[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:17     ERROR   [Redis]  [string]  redis disconnected 
[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:17     ERROR   [Redis]  [string]  redis disconnected 
[Evolution API]    v2.3.6  317   -  Thu Nov 27 2025 21:16:18     ERROR   [Redis]  [string]  redis disconnected 
(continues infinitely...)

These logs indicate that the Redis client is initializing but failing to maintain a stable connection, leading to the continuous disconnection errors.

Redis Logs

In contrast, the Redis logs show that the server is running correctly and accepting connections:

1:M 27 Nov 2025 23:04:56.454 * Running mode=standalone, port=6379.
1:M 27 Nov 2025 23:04:56.454 * Server initialized
1:M 27 Nov 2025 23:04:56.454 * Ready to accept connections tcp

This further confirms that the issue is not with the Redis server itself but with the client within the Evolution API.

Impact and Implications

The Redis connection bug in Evolution API v2.3.6 has several significant impacts:

  • Inability to Use Redis for Caching: The primary impact is the inability to utilize Redis for caching, which is crucial for performance optimization.
  • Performance Degradation: Without Redis caching, the API's performance can be significantly degraded, especially under heavy load.
  • Scalability Limitations: The lack of Redis support hinders horizontal scaling, as multiple instances cannot efficiently share cached data.
  • Single-Instance Operation: The API functions perfectly without Redis, but only in a single-instance setup, limiting its scalability and resilience.

These implications underscore the importance of resolving this bug to fully leverage the capabilities of Evolution API.

Potential Causes and Solutions

Based on the diagnostics and observations, here are some potential causes and solutions for the Redis connection issue:

1. Redis Client Configuration

  • Cause: Incorrect configuration of the Redis client within the Evolution API. This could include issues with connection parameters, authentication, or other client-specific settings.
  • Solution: Review the Redis client initialization code in the CacheEngine module and ensure that all connection parameters are correctly set. Double-check the REDIS_URI and REDIS_PASSWORD environment variables and verify that they match the Redis server configuration.

2. Connection Pooling Issues

  • Cause: Problems with connection pooling, where the API is unable to manage and reuse Redis connections efficiently. This can lead to connection exhaustion and disconnections.
  • Solution: Examine the connection pooling implementation in the API and ensure that it is properly configured. Adjust the maximum number of connections, connection timeout, and other pooling parameters as needed. Consider using a robust connection pooling library that handles connection management effectively.

3. Network Issues

  • Cause: Although the user confirmed basic network connectivity, there might be intermittent network issues or firewall configurations that are interfering with the Redis connection.
  • Solution: Investigate network logs and firewall rules to identify any potential issues. Ensure that there are no restrictions on communication between the Evolution API and Redis containers. Use network monitoring tools to track connection latency and packet loss.

4. Version-Specific Bug

  • Cause: As suggested by the user and other reports, this bug might be specific to v2.3.6. There might be an issue in the Redis client implementation that was introduced in this version.
  • Solution: Consider downgrading to a previous version of Evolution API where Redis connections were stable. Alternatively, monitor the Evolution API repository for updates and bug fixes related to Redis connectivity. Engage with the Evolution API community to share your findings and seek further assistance.

5. Asynchronous Connection Handling

  • Cause: Issues with asynchronous connection handling can lead to race conditions or unhandled exceptions, causing the connection to fail silently.
  • Solution: Review the asynchronous code related to Redis connections and ensure that all promises and callbacks are handled correctly. Implement proper error handling and logging to capture any exceptions that occur during connection establishment or maintenance.

Steps for Resolving the Issue

Here’s a structured approach to resolving the Redis connection bug:

  1. Review Redis Configuration: Double-check all Redis-related environment variables and ensure they are correctly configured.
  2. Examine Redis Client Code: Investigate the CacheEngine module and the Redis client initialization code for any configuration errors or issues.
  3. Check Connection Pooling: Verify the connection pooling implementation and adjust parameters as needed.
  4. Monitor Network Connectivity: Use network monitoring tools to track connection latency and packet loss between the API and Redis containers.
  5. Consider Version Downgrade: If the issue is specific to v2.3.6, consider downgrading to a previous version.
  6. Engage with the Community: Share your findings and seek assistance from the Evolution API community.
  7. Implement Error Handling: Ensure proper error handling and logging in the asynchronous code related to Redis connections.

By systematically addressing these potential causes, you can effectively troubleshoot and resolve the Redis connection issues in Evolution API v2.3.6.

Conclusion

The Redis connection failure in Evolution API v2.3.6 is a challenging issue that can significantly impact performance and scalability. By understanding the symptoms, diagnosing the problem, and systematically addressing potential causes, you can resolve this bug and leverage the benefits of Redis caching. This article has provided a comprehensive guide to troubleshooting and fixing Redis connection issues, empowering you to get your Evolution API running smoothly.

For further information and community support, consider visiting the official Evolution API GitHub repository.