Scope: Valkey and Redis OSS engines only. Memcached uses SASL authentication (1.6.12+) and does not support RBAC user groups or IAM auth. Memcached error patterns differ and are not covered here.
ElastiCache-specific errors that require non-obvious remediation. Generic errors (AUTH required, TLS handshake, DNS resolution, timeouts, replication lag, throttling, slow commands) are omitted; see monitoring/troubleshooting.md for metric-based diagnosis of those.
Symptom: Client gets Connection refused or ECONNREFUSED when connecting to the cache endpoint.
Causes:
Security group does not allow inbound TCP on port 6379 (or 6380 for serverless read port) from the client’s security group or IP.
The cache endpoint is incorrect or the cache is not in available state.
The client is outside the VPC (ElastiCache has no public endpoints).
Subnet routing issue: the client’s subnet cannot reach the cache’s subnet.
Next steps:
Verify the cache is in available status: aws elasticache describe-serverless-caches or describe-replication-groups.
Check the security group attached to the cache allows inbound from the client’s security group on port 6379.
Confirm the client is in the same VPC or has a valid network path (VPC peering, transit gateway, or tunnel).
For serverless, verify both ports 6379 (primary port for reads and writes) and 6380 (read port for eventually-consistent reads via READONLY) are allowed; both use the same hostname.
Symptom:WRONGPASS invalid username-password pair or ERR invalid password.
Causes:
Incorrect password or expired IAM auth token.
RBAC user password was rotated but the client is using the old password.
IAM auth token expired (tokens are valid for 15 minutes).
Wrong username specified.
Next steps:
For IAM auth: regenerate the token. Tokens expire after 15 minutes for new AUTH/HELLO; an already-authenticated connection remains valid for up to 12 hours. Sending AUTH (or HELLO with auth) using a new IAM token resets the 12-hour disconnect timer.
For password auth: retrieve the current password from Secrets Manager.
Verify the username matches an active RBAC user associated with the cache’s user group.
If the password is correct but commands still fail, check for NOPERM errors (section 7), which indicate access-string restrictions rather than credential issues.
Symptom:MOVED <slot> <ip>:<port> response from the server.
Causes:
The client sent a command to a node that does not own the hash slot for the key. This happens with cluster-mode-enabled deployments when the client is not using a cluster-aware driver.
Next steps:
Use a cluster-aware client library (e.g., redis-py with RedisCluster, ioredis with Cluster mode, Lettuce with cluster topology refresh).
Do not use a standalone client to connect to a cluster-mode-enabled cache.
Verify the client is connected to the configuration endpoint, not an individual node endpoint.
Symptom:OOM command not allowed when used memory > 'maxmemory' or ERR command not allowed when maxmemory is set and the server is currently unable to free memory.
Causes:
The cache has reached its configured maxmemory limit and the current eviction policy (maxmemory-policy) does not allow the write.
noeviction policy is set, preventing automatic key eviction.
Next steps:
Check DatabaseMemoryUsagePercentage in CloudWatch.
If the eviction policy is noeviction, consider changing to allkeys-lru or volatile-lru depending on the use case.
Scale up the node type for more memory, or add shards to distribute data.
Review TTLs on keys; ensure transient data has appropriate expiry.
Use MEMORY USAGE <key> to identify large keys consuming disproportionate memory.
Symptom:CROSSSLOT Keys in request don't hash to the same slot.
Causes:
A multi-key command (MGET, MSET, pipeline with multi-key operations, Lua script with multiple keys) targets keys that hash to different slots in a cluster-mode-enabled deployment.
Next steps:
Use hash tags to force related keys to the same slot: {user:123}:profile, {user:123}:sessions.
Split multi-key operations into per-slot batches.
If the workload cannot use hash tags, consider a single-shard deployment (if data fits).
Review the client library’s support for automatic slot-aware batching.
Symptom:NOPERM this user has no permissions to run the '<command>' command or NOPERM... on key '<key>'.
Causes:
The RBAC user’s access string does not permit the command category or key pattern.
The user is restricted to specific key prefixes and the application is accessing keys outside that prefix.
Next steps:
Check the user’s access string: aws elasticache describe-users --user-id <user-id>.
Update the access string to include the required command categories and key patterns.
Common fix: change on ~app:* +@read to on ~app:* +@read +@write if writes are needed.
Access string changes (via aws elasticache modify-user) take effect immediately on all existing connections authenticated as that user — not just new ones. However, setting a user to off only prevents new AUTH attempts (it does not disconnect existing connections). To delete a user, use aws elasticache delete-user; ElastiCache does not support the ACL DELUSER command. Deleting a user via the API removes them from all associated user groups.
The node has reached its maximum connection limit.
Connection leaks in the application (connections opened but never closed).
Missing connection pooling.
Next steps:
Check CurrConnections metric in CloudWatch.
Implement connection pooling in the application.
For node-based: scale up the node type (larger nodes support more connections). For serverless: connection scaling is automatic; max-clients errors indicate per-connection ECPU starvation or client-side connection leaks, not server capacity.
Investigate and fix connection leaks (common in Lambda without reuse across invocations).
Check for idle connections that can be closed with timeout parameter.
Symptom: Snapshot creation fails or takes excessively long.
Causes:
Insufficient memory for the fork operation (background save requires memory overhead).
Node type with limited resources.
Next steps:
Ensure reserved-memory-percent leaves enough headroom for fork operations. The default is 25 for accounts created after March 16, 2017. Older accounts may default to 0. AWS recommends 25% for all deployments.
Schedule snapshots during low-traffic periods.
Scale up the node type if memory is tight during snapshot creation.
Symptom:InvalidParameterCombination when creating or modifying a cluster.
Causes:
Parameter group family does not match the engine and version.
Conflicting parameters specified.
Next steps:
Verify the parameter group family matches the engine. Documented valid values include: memcached1.4, memcached1.5, memcached1.6, redis2.6, redis2.8, redis3.2, redis4.0, redis5.0, redis6.x, redis6.2, redis7, valkey7, valkey8. Use describe-engine-default-parameters to confirm the correct family name for your engine version.
Check describe-engine-default-parameters for valid parameter names and ranges.
Create a new parameter group from the correct family.
Symptom:NOPERM or authentication error during a MULTI/EXEC transaction on an IAM-authenticated connection.
Causes:
The IAM auth token expired during the transaction and the client attempted to re-AUTH (call AUTH again) inside the MULTI block. Re-authentication inside a transaction is not supported.
MULTI/EXEC itself works correctly on IAM-authenticated connections. The limitation is that token refresh cannot happen between MULTI and EXEC.
Next steps:
Refresh the IAM auth token before issuing MULTI, not inside the transaction. Ensure the token will remain valid for the duration of the transaction.
Use a connection pool that rotates IAM tokens on idle reconnect or before checkout, so connections handed to application code always have a fresh token.
If token expiry during long transactions is unavoidable, establish a new connection with a fresh token and retry the transaction.