When working with Redis, few moments are as frustrating as encountering the ‘WRONGPASS Invalid username-password pair’ error. You’re absolutely certain the password is correct, yet authentication keeps failing. If this sounds familiar, you’re likely dealing with something more complex than a simple typo.
This issue has become increasingly common among developers using Redis 6.0+, especially those upgrading from earlier versions. The problem often stems from significant changes in Redis’s authentication system that many developers aren’t aware of.
1. The Root Cause: Redis 6.0 ACL System Changes
The primary culprit behind this error is the ACL (Access Control List) system introduced in Redis 6.0. This represented a fundamental shift from the simple requirepass approach to a sophisticated user-based permission management system, fundamentally changing how authentication works.
Legacy vs Modern Authentication
# Redis 5.x and earlier (Legacy approach)
AUTH password123
# Redis 6.0+ (Modern ACL approach)
AUTH username password123
# or
AUTH default password123
In Redis 6.0+, connections work by authenticating both username and password after establishing the connection. The default user exists implicitly and can perform certain operations without explicit authentication, which creates some unexpected behavior patterns.
2. Primary Solutions by Root Cause
2-1. Connection URL Format Issues
One of the most common mistakes involves improper colon (:) usage in connection URLs. This trips up even experienced developers.
Incorrect Examples:
// ❌ Wrong format
redis://:username:password@host:port/db
// ❌ Unnecessary colon before username
redis://:default:123456@localhost:6379/0
Correct Examples:
// ✅ Correct format (with both username and password)
redis://username:password@host:port/db
// ✅ Password-only authentication (default user)
redis://:password@host:port/db
// ✅ Specific examples
redis://myuser:mypassword@localhost:6379/0
redis://:secretpass@localhost:6379/0
The key insight is that the colon before the username should only be used when you have a password but no explicit username (i.e., using the default user).
2-2. Default User Configuration Check
Redis 6.0+ automatically creates a default user. Let’s verify the current user configuration:
# Check current user list in Redis CLI
127.0.0.1:6379> ACL LIST
1) "user default on nopass ~* +@all"
# Check specific user information
127.0.0.1:6379> ACL GETUSER default
If the default user is disabled:
# Enable the default user
127.0.0.1:6379> ACL SETUSER default on
# Set password for default user
127.0.0.1:6379> ACL SETUSER default >yourpassword
2-3. Cloud Service-Specific Configurations
AWS ElastiCache
When using IAM authentication with AWS ElastiCache, user IDs and usernames must be identical and lowercase, with temporary security credentials serving as the password.
# ElastiCache IAM authentication example
redis-cli -h your-cluster.cache.amazonaws.com -p 6379 --tls \
--user your-iam-user-id \
--askpass
Azure Cache for Redis
# Azure requires username:password format
redis-cli -h your-cache.redis.cache.windows.net -p 6380 --tls \
-a "username:password"
Google Cloud Memorystore
# Google Cloud with AUTH string
redis-cli -h your-instance-ip -p 6379 -a your-auth-string
3. Language-Specific Solutions
3-1. Node.js (node-redis)
The Node.js redis client changed authentication handling after version 3.1.0, causing WRONGPASS errors with legacy connection patterns.
// ❌ Problematic code (legacy approach)
const redis = require('redis');
const client = redis.createClient({
host: 'localhost',
port: 6379,
password: 'yourpassword'
});
// ✅ Fixed code (modern approach)
const redis = require('redis');
const client = redis.createClient({
url: 'redis://:yourpassword@localhost:6379',
// or with username
// url: 'redis://username:password@localhost:6379'
});
// ✅ Alternative explicit authentication
const client = redis.createClient({
socket: {
host: 'localhost',
port: 6379
},
username: 'default', // or actual username
password: 'yourpassword'
});
3-2. Python (redis-py)
import redis
# ✅ Correct connection methods
# Method 1: URL approach
r = redis.from_url('redis://:password@localhost:6379/0')
# Method 2: Parameter approach
r = redis.Redis(
host='localhost',
port=6379,
username='default', # Explicitly specify for Redis 6.0+
password='yourpassword',
db=0
)
# Method 3: With custom username
r = redis.Redis(
host='localhost',
port=6379,
username='myuser',
password='mypassword',
db=0
)
3-3. Java (Jedis)
import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisPool;
import redis.clients.jedis.JedisPoolConfig;
// ✅ Correct connection approach
public class RedisConnection {
private JedisPool jedisPool;
public void initializePool() {
JedisPoolConfig config = new JedisPoolConfig();
// Redis 6.0+ ACL user authentication
jedisPool = new JedisPool(config, "localhost", 6379,
2000, "default", "yourpassword");
// Or with custom username
// jedisPool = new JedisPool(config, "localhost", 6379,
// 2000, "username", "password");
}
}
3-4. Go (go-redis)
package main
import (
"github.com/go-redis/redis/v8"
"context"
)
func main() {
// ✅ Correct Redis 6.0+ connection
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
Username: "default", // Specify username explicitly
Password: "yourpassword",
DB: 0,
})
// Test connection
ctx := context.Background()
_, err := rdb.Ping(ctx).Result()
if err != nil {
panic(err)
}
}
4. Real-time Debugging and Diagnostics
4-1. Live Connection Monitoring
# Monitor real-time commands on Redis server
127.0.0.1:6379> MONITOR
# Check client connection information
127.0.0.1:6379> CLIENT LIST
# Verify currently authenticated user
127.0.0.1:6379> ACL WHOAMI
4-2. Step-by-Step Diagnostic Process
Step 1: Basic Connection Test
# Basic connection (no password)
redis-cli -h localhost -p 6379
127.0.0.1:6379> PING
Step 2: Password-only Authentication
redis-cli -h localhost -p 6379
127.0.0.1:6379> AUTH yourpassword
Step 3: Username and Password Authentication
redis-cli -h localhost -p 6379
127.0.0.1:6379> AUTH default yourpassword
# or
127.0.0.1:6379> AUTH username password
4-3. Log Analysis
Check Redis server logs for authentication-related messages:
# Monitor Redis logs in real-time
tail -f /var/log/redis/redis-server.log
# Or in Docker environment
docker logs -f your-redis-container
# For systemd-based systems
journalctl -f -u redis-server
5. Common Error Scenarios and Solutions
Scenario 1: Version Upgrade Issues
# When upgrading from Redis 5.x to 6.0+
# 1. Check existing requirepass setting
127.0.0.1:6379> CONFIG GET requirepass
# 2. Migrate to ACL
127.0.0.1:6379> ACL SETUSER default on >currentpassword ~* +@all
# 3. Save configuration
127.0.0.1:6379> CONFIG REWRITE
Scenario 2: Client Library Compatibility Issues
| Language | Library | Minimum Version | Notes |
|---|---|---|---|
| Node.js | node-redis | 4.0.0+ | ACL issues in 3.1.0 and below |
| Python | redis-py | 3.5.0+ | Username parameter support |
| Java | Jedis | 3.6.0+ | Full ACL user authentication |
| Go | go-redis | 8.0.0+ | Complete Redis 6.0 ACL support |
| .NET | StackExchange.Redis | 2.2.0+ | ACL username support |
Scenario 3: Kubernetes and Orchestration Environments
# Kubernetes ConfigMap for Redis
apiVersion: v1
kind: ConfigMap
metadata:
name: redis-config
data:
redis.conf: |
requirepass secretpassword
user default on >secretpassword ~* +@all
user appuser on >apppass ~app:* +@read +@write -@dangerous
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: redis
spec:
replicas: 1
selector:
matchLabels:
app: redis
template:
metadata:
labels:
app: redis
spec:
containers:
- name: redis
image: redis:7-alpine
command: ["redis-server", "/etc/redis/redis.conf"]
volumeMounts:
- name: config
mountPath: /etc/redis/redis.conf
subPath: redis.conf
volumes:
- name: config
configMap:
name: redis-config
6. Advanced Troubleshooting Techniques
6-1. Network and Connectivity Issues
# Test network connectivity
telnet your-redis-host 6379
# Check if Redis is listening on expected interface
netstat -tlnp | grep 6379
# Verify Redis is accepting connections
redis-cli -h your-redis-host -p 6379 ping
6-2. SSL/TLS Configuration Issues
# Connect with TLS (required for many cloud providers)
redis-cli -h your-host -p 6380 --tls --cert client.crt --key client.key --cacert ca.crt
# Test TLS connection
openssl s_client -connect your-host:6380
6-3. Memory and Performance Diagnostics
# Check Redis info for authentication stats
127.0.0.1:6379> INFO stats
# Monitor authentication failures
127.0.0.1:6379> INFO commandstats
# Check connected clients and their authentication status
127.0.0.1:6379> CLIENT LIST
7. Troubleshooting Checklist
Follow this checklist systematically:
✅ Basic Verification
- [ ] Confirm Redis version is 6.0 or higher
- [ ] Verify connection URL format (
redis://username:password@host:port/db) - [ ] Check client library version compatibility
- [ ] Test basic network connectivity
✅ Authentication Method Verification
- [ ] Try
AUTH username passwordformat - [ ] Check default user status and configuration
- [ ] Verify ACL user list and permissions
- [ ] Test with explicit username parameter in client
✅ Environment-Specific Checks
- [ ] Verify cloud service authentication requirements (AWS IAM, Azure AD, etc.)
- [ ] Check Docker/Kubernetes network configuration
- [ ] Confirm SSL/TLS requirements and certificates
- [ ] Validate environment variables and secrets
✅ Logging and Monitoring
- [ ] Review Redis server logs for authentication errors
- [ ] Use
MONITORcommand for real-time command tracking - [ ] Check client connection status and health
- [ ] Analyze authentication failure patterns
This comprehensive guide should resolve your Redis authentication issues completely. By understanding the ACL system changes and implementing proper authentication patterns, you’ll not only fix current problems but also build a more secure and maintainable Redis setup. The key is recognizing that Redis 6.0+ requires a fundamentally different approach to authentication, and adapting your applications accordingly.