How do I troubleshoot connection issues for ElastiCache Serverless for Valkey and ElastiCache Serverless for Redis OSS clusters?

Short Description

ElastiCache Serverless uses a dual-endpoint architecture with port 6379 for write operations and port 6380 for read operations. You can access these endpoints only from resources that reside within the same Amazon VPC as the ElastiCache cluster.

Note: For more information, see Accessing an ElastiCache Cache when it and the Amazon Elastic Compute Cloud (Amazon EC2) Instance are in Different Amazon VPCs.

Resolution

To troubleshoot connectivity issues with your ElastiCache Serverless cluster, complete the following tasks.

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.

Review your cluster status

Before you connect to your cluster, check the status of the cluster to make sure that your cluster is fully operational. Clusters can be in the following statuses:

• For the Creating status, the cluster creation is in progress.
• For the Modifying status, the configuration updates are currently happening.
• For the Available status, the cluster is ready for configurations.

Before you attempt to connect, wait for the cluster to be in an Available status. Clusters in the Creating or Modifying states can't accept connections.

To check the status of a cluster, use the ElastiCache console. Or, run the AWS CLI describe-serverless-caches command:

aws elasticache describe-serverless-caches
--serverless-cache-name your-serverless-cache-name

Note: Replace your-serverless-cache-name with the name of your cache.

Review your security group settings

Configure the ElastiCache cluster's security groups to permit inbound access on both port 6379 (write endpoint) and port 6380 (read endpoint). Without access to both ports, you might experience a Connection timed out error. During the start of the connection process, Redis clients might try to connect to both 6379 and 6380 ports. If your security group blocks access to either port, then your connection establishment experiences delays. For more information, see Troubleshooting high latency in ElastiCache Serverless.

To review and update your security group settings, complete the following steps:

1. Open the Amazon VPC console.
2. In the navigation pane, choose Security Groups.
3. Select the security group associated with your ElastiCache cluster.
4. On the Inbound Rules tab, verify that you allow inbound access from TCP ports 6379 and 6380 for the security group. If you don't allow inbound access, then edit the inbound rules to grant network access on both ports.

Test your client-to-cluster network connectivity

From an Amazon EC2 instance in the same VPC, run the telnet or nc commands to test your client-to-cluster connectivity.

telnet example:

# Test connection to write endpoint (port 6379)
telnet write-endpoint 6379

# Test connection to read endpoint (port 6380)
telnet read-endpoint 6380

nc example:

# Test connection to write endpoint (port 6379)
nc -zv write-endpoint 6379

# Test connection to read endpoint (port 6380)
nc -zv read-endpoint 6380

Note: Replace write-endpoint and read-endpoint with your cache endpoints.

If the connection succeeds from the EC2 instance but fails from your client, then the network has one of the following issues:

• The security group has misconfigurations for your client resource. Update the security groups for your client resource to allow outbound connections to the cluster IP on both ports 6379 and 6380.
• The network access control lists (network ACLs) has misconfigurations in your client's subnet. Update the network ACLs in your client's subnet to allow outbound connections on ports 6379 and 6380.
• The routing tables are incorrectly setup for your client resource. Update the routing tables for your client's subnet to make sure that routes exist to the ElastiCache cluster.

For more information, see Access patterns for accessing an ElastiCache cache in an Amazon VPC.

Verify in-transit encryption for cluster connections

By default, ElastiCache Serverless enforces mandatory in-transit encryption for all cluster connections. To connect to your ElastiCache Serverless cluster, configure your client application with TLS/SSL support. To verify TLS encryption for your ElastiCache Serverless cluster connections, run the s_client command for OpenSSL. Or, run the redis-cli command.

For OpenSSL:

The OpenSSL s_client utility is a diagnostic tool that tests TLS/SSL connections. To validate the secure connection to your ElastiCache cluster, run the following command from the cluster:

openssl s_client -connect your-cluster-endpoint:6379
openssl s_client -connect your-cluster-endpoint:6380

Note: Replace your-cluster-endpoint with your cache endpoint.

The output must show a successful TLS/SSL handshake, proper certificate chain, and a valid protocol version.

Example output:

# Verify TLS connection for write endpoint 
openssl s_client -connect my-cluster-endpoint:6379
Example output:
CONNECTED(00000003)
depth=2 C = US, O = Amazon, CN = Amazon Root CA 1
verify return:1
depth=1 C = US, O = Amazon, CN = Amazon RSA 2048 M02
verify return:1
depth=0 CN = *.serverless.use1.cache.amazonaws.com
verify return:1
---
Certificate chain
.
.
---
SSL handshake has read 5566 bytes and written 414 bytes
Verification: OK
---
New, TLSv1.3, Cipher is TLS_AES_128_GCM_SHA256
.
---

# Verify TLS connection for read endpoint
 openssl s_client -connect my-cluster-endpoint:6380

-or-

For redis-cli:

To use the redis-cli with TLS support and establish a connection to your cluster, run the following command:

redis-cli -h your-cluster-endpoint --tls -c

Note: Replace your-cluster-endpoint with your cache endpoint

If the connection is successful, then the output looks similar to the following example output:

your-cluster-endpoint:6379>

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

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

To resolve this issue, install a redis-cli version that includes TLS support. For more information, see Connecting to ElastiCache (Valkey) or Amazon ElastiCache for Redis OSS with in-transit encryption using valkey-cli.

Note: A successful OpenSSL or redis-cli test confirms TLS support at the network level. Configure your Redis client to use TLS.

If you verify TLS connectivity but still can't connect to your ElastiCache Serverless cluster, then review your application configurations for the following potential issues:

• Because ElastiCache Serverless enforces in-transit encryption, your application must support TLS/SSL to connect to ElastiCache Serverless.
• If your TLS/SSL configurations aren't correct, configure the configuration flags or trusted certification authorities for your ElastiCache Serverless cluster.
• To use TLS/SSL encryption when you connect to the ElastiCache Serverless endpoint, verify that you configured your application's Redis client library.

Verify that your client is cluster aware

When you connect to an ElastiCache Serveless for Redis OSS cluster with cluster mode enabled, you might get the following error message:

MOVED <slot> <IP>:<port>

Redis sends these error messages to indicate that ElastiCache relocated the hash slot to a different node during a resharding or failover event. Most modern Redis clients are cluster-aware and automatically update internal slot mapping and retry requests on the correct node to handle these errors. For clusters that aren't cluster-aware, these clients can't process the errors, and you get persistent connection issues.

To resolve these errors, use a Redis client library or package that supports cluster mode and is cluster-aware. The follow are examples of cluster-aware clients:

• Java Jedis
• Python redis-py-cluster
• Node.js ioredis (version 4.0.0 and later)

Review your DNS Configuration

If you receive a Name or service not known or NXDOMAIN error, then you might have issues with your DNS configuration. To resolve these issues, complete the following tasks:

• Find your Redis cluster and review the cluster details. Then, update your endpoint in the ElastiCache console, and make sure that the Endpoint value matches the same value that you use in your application or client code.
  Note: The endpoint looks similar to the following example: [CLUSTER_NAME]-[CLUSTER_ID].serverless.[REGION].cache.amazonaws.com
• Update your DNS attributes on the Amazon VPC client resource.

Review your authentication connection parameters

If you try to connect to an ElastiCache cluster that has authentication turned on, then you might get the NOAUTH Authentication required or AUTH Failed error message.

When you use the valkey-cli to connect to the cluster, ElastiCache Serverless requires both the --tls and --askpass (or -a) parameters. If these parameters are missing or you use incorrect credentials, then you get one of the preceding error messages.

To resolve this issue, include the correct parameters when you connect to your cluster.

Example:

src/redis-cli -h your-cluster-endpoint --tls -c --user your-user -a your-password # Using redis-cli with direct password 
src/redis-cli -h your-cluster-endpoint --tls -c --user your-user --askpass # Using redis-cli with password prompt (more secure) 
src/redis-cli -h your-cluster-endpoint --tls -c > AUTH your-user your-password # If already connected without auth, use AUTH command 

Important: For security compliance, don't include credentials in command lines. To manage authentication, use environment variables or password files.

Separate your read and write operations

For ElastiCache Serverless, there's a maximum limit of 3,999 arguments per request. If you exceed this limit, then you get a Connection reset by peer error on your Redis client.

To resolve this issue, separate read and write operations across different ports. Configure your client to use port 6380 for read operations and port 6379 for write operations

Review your cluster health

To review your cluster's health, review the following sources:

• For event logs, check for any failed events for your Serveless cluster. If there are failed events, then resolve the issues based on the failed event messages.
• Monitor Amazon CloudWatch metrics for your ElastiCache Serverless cluster. For more information, see Monitoring best practices with Amazon ElastiCache for Redis using Amazon CloudWatch.

Related information

Accessing your ElastiCache cluster or replication group

How do I resolve Redis client read requests that are redirected to the primary node of a shard instead of a replica node in ElastiCache for Redis?

Authenticating with the Valkey and Redis OSS AUTH command

Valkey and Redis OSS configuration and limits