How do I troubleshoot connection issues for ElastiCache for Valkey and ElastiCache for Redis OSS self-designed clusters?

Resolution

Check the state of your cluster

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

If you recently created the cluster, then you might experience connectivity issues if the cluster isn't in the Available state. To confirm that creation is complete, check the status of the cluster and each node attached to the cluster:

• If the Status column shows Available, then the cluster is ready to accept connections.
• If the Status column shows Creating or Modifying, then cluster creation is in progress or updating. Wait a few minutes until the status updates to Available.

Check the health of your cluster

To check the cluster's health, review the following sources for information on your cluster:

• Review your cluster's recent events for the timeframe when the issue occurred.
• Review the Amazon CloudWatch metrics for an overview of the cluster's health. For more information, see Monitoring best practices with Amazon ElastiCache for Redis using Amazon CloudWatch.

Review your security groups and network ACL configurations

Review the configurations for your security groups and network access control lists (network ACLs) on the cluster and resource that you initiate the connection from. You must configure the security groups and network ACLs to access resources. For more information, see Accessing your ElastiCache cluster or replication group.

The following are examples of client resources:

• Amazon Elastic Compute Cloud (Amazon EC2) instances
• AWS Lambda functions
• Amazon Elastic Container Service (Amazon ECS) containers
• Amazon Elastic Kubernetes Service (Amazon EKS) containers

To review the cluster's security group, complete the following steps:

1. Open the ElastiCache console.
2. In the navigation pane, under Resources, choose Valkey caches or Redis OSS caches, and then select the cluster.
3. On the cluster details page, select the Connectivity and security tab.
4. Check that at least one of the associated security groups allows inbound connections from the client resource to the cluster on the cluster's port.
5. To find the port number, review any of the cluster endpoints. The endpoints are in the domain_name:port format.
   Note: By default, the cluster's port is 6379/TCP. When you create a cluster, you can override the port number.
6. On the client resource, check that the security groups allow outbound connections from the cluster's port to the CIDR blocks of the cluster's subnets.
7. Check that the network ACLs allow outgoing and incoming connections between the client and the cluster. Also, check that the route tables have the appropriate routes.
   Note: By default, network ACLs allow all connections.

To further troubleshoot network configuration, use the Amazon Virtual Private Cloud (Amazon VPC) Network Access Analyzer.

Check that you use the correct endpoints for connections

Make sure that you configure the client side application to use the correct endpoints. For more information, see Finding connection endpoints in ElastiCache.

Review the TCP connection between the Valkey or Redis OSS cluster and the client

Make sure that there's a TCP connection between the Valkey or Redis OSS cluster and the client resource. To confirm connectivity between the ElastiCache cluster and the client, run the curl command from the client resource:

$ curl -v telnet://example-cluster-endpoint:6379

Note: Replace example-cluster-endpoint with your cluster's endpoint.

Example output:

*   Trying 172.31.1.242:6379...* Connected to example-cluster-endpoint (172.31.1.242) port 6379

In the preceding example, Connected in the output confirms that the TCP connection is successful.

Review connections to clusters that have in-transit encryption

To send Valkey or Redis OSS cluster traffic over TLS, you must use in-transit encryption. To establish a connection from the client, the client must have TLS support.

If you have valkey-cli or redis-cli with TLS support, then you can add the --tls argument to the command to turn on TLS support.

redis-cli example:

$ redis-cli -h example-encrypted-cluster-endpoint -p 6379 --tls 

valkey-cli example:

$ valkey-cli -h example-encrypted-cluster-endpoint -p 6379 --tls

Note: Replace example-encrypted-cluster-endpoint with your cluster's encrypted endpoint.

Example output:

example-encrypted-cluster-endpoint:6379>

If your valkey-cli or redis-cli doesn't have TLS support, then you get the following error:

"Unrecognized option or bad number of args for: '--tls' "

To troubleshoot the preceding error, install valkey-cli or redis-cli with TLS support.

Review connections to clusters with authentication

To review connections to clusters with authentication, use valkey-cli or redis-cli. For more information, see the Connecting to an encryption/authentication enabled cluster section in Connect to the cluster's node.

redis-cli example:

redis-cli -h your-cluster-endpoint -p 6379 --tls -c --user your-user --askpass # Enter the password when prompted

valkey-cli example:

valkey-cli -h your-cluster-endpoint -p 6379 --tls -c --user your-user --askpass # Enter the password when prompted 

Note: The valkey-cli and redis-cli commands require both the --tls and --askpass or -a arguments. If you don't provide these arguments or use an incorrect password, then a NOAUTH or AUTH failed message appears. If you use valkey-cli or redis-cli only with --tls argument, then use AUTH <password> after you connect to complete the authentication.

Update the DNS attributes on your client resource

If you have DNS issues, then you might receive a "Name or service not known" or "NXDOMAIN" error. These errors occur when DNS lookups fail through your custom DNS server. To resolve these errors, make sure that you have the correct DNS attributes on the Amazon VPC client resource.

Note: It's a best practice to use the Amazon DNS server for your virtual private cloud (VPC).

Review your client connections

To review the client connection details of your ElastiCache cluster, you can use metrics for Valkey and Redis OSS, such as CurrConnections and NewConnections. ElastiCache uses four to six of the connections to monitor the cluster.

To find your client connection details, run the following valkey-cli or redis-cli command:

$ CLIENT LIST

The output of the command lists all connected clients, including their IP addresses, idle time, and other information. For more information, see CLIENT LIST on the Valkey website and CLIENT LIST on the Redis OSS website.

Review the network connectivity between your cluster and the client resource

Depending on how you access your ElastiCache cluster, you might experience latency issues. To minimize latency, it's a best practice to access ElastiCache from Amazon EC2 or from resources within the same Amazon VPC. For more information, see Access Patterns for accessing an ElastiCache cache in an Amazon VPC and Accessing your ElastiCache cluster or replication group.

Related information

Persistent connection issues

Connect to a Valkey or Redis OSS cluster or replication group (Linux)