🚨 Redis Error Guide: 'WRONGPASS invalid username-password pair or user is disabled' — Fix the Credential or ACL User

Overview

WRONGPASS means the client did send credentials, but they were rejected: the password does not match, the username is unknown, or the ACL user exists but is disabled (off). Unlike NOAUTH (no credentials sent), WRONGPASS tells you authentication was attempted and failed.

The literal error clients receive:

(error) WRONGPASS invalid username-password pair or user is disabled.

Redis deliberately keeps this message vague — it will not tell you whether it was the username or the password that was wrong, to avoid leaking which usernames exist. That vagueness is why the diagnosis is about systematically checking the credential, the ACL user state, and whether a rotation left the client with a stale secret.

Symptoms

• AUTH fails with WRONGPASS even though the client is sending a password.
• Started right after a password rotation or an ACL change.
• One service authenticates fine while another (using a different secret) fails.

redis-cli --user app --pass 'oldpass' PING 2>/dev/null

(error) WRONGPASS invalid username-password pair or user is disabled.

redis-cli --user app --pass 'newpass' PING 2>/dev/null

PONG

Common Root Causes

1. Wrong or stale password

The most common case: the password was rotated on the server but the client still uses the old one.

# Verify with the known-good password
redis-cli -a '<CURRENT_PASS>' PING 2>/dev/null
grep -E '^requirepass' /etc/redis/redis.conf

2. ACL user is disabled (off)

The user exists but was disabled, so any password is rejected.

redis-cli -a '<ADMIN_PASS>' ACL GETUSER app

1) "flags"
2) 1) "off"

off in the flags means the user cannot authenticate regardless of password.

3. Wrong username

The client authenticates as a username that does not exist, or uses default when a named user is required.

redis-cli -a '<ADMIN_PASS>' ACL LIST
redis-cli -a '<ADMIN_PASS>' ACL USERS

1) "default"
2) "app"
3) "metrics"

4. Password hash mismatch after ACL edit

An ACL SETUSER that reset the password (or a config reload that overwrote ACLs from aclfile) leaves clients on the old secret.

redis-cli -a '<ADMIN_PASS>' ACL GETUSER app | sed -n '/passwords/,+2p'
grep -E '^aclfile|^user ' /etc/redis/redis.conf

Diagnostic Workflow

Step 1: Confirm which auth model is in use

grep -E '^requirepass|^user |^aclfile' /etc/redis/redis.conf
redis-cli -a '<ADMIN_PASS>' ACL WHOAMI 2>/dev/null

requirepass only → single password. user/aclfile lines → ACL model with usernames.

Step 2: Test the exact credential the client uses

redis-cli -h <HOST> --user app --pass '<PASS>' PING 2>/dev/null
# Single-password model:
redis-cli -h <HOST> -a '<PASS>' PING 2>/dev/null

WRONGPASS here confirms the credential itself is bad; PONG means the client config differs from what you tested.

Step 3: Inspect the ACL user state

redis-cli -a '<ADMIN_PASS>' ACL GETUSER app
redis-cli -a '<ADMIN_PASS>' ACL LIST

Look for off (disabled) and confirm the username exists.

Step 4: Check for a recent rotation or ACL reload

sudo journalctl -u redis-server --no-pager | grep -iE 'ACL|CONFIG SET requirepass|LOAD' | tail
redis-cli -a '<ADMIN_PASS>' ACL LOG 10

ACL LOG records recent auth failures with the reason and username.

Step 5: Confirm client config source

grep -Eri 'REDIS_URL|REDIS_PASSWORD|--user|--pass' /etc/myapp/ 2>/dev/null

Example Root Cause Analysis

At 11:20 the reporting job starts failing every Redis call with WRONGPASS invalid username-password pair or user is disabled. Other services are unaffected, which points at that one job’s credential rather than a server-wide outage.

ACL LOG on the server shows the failures and the username involved:

redis-cli -a 'AdminPass' ACL LOG 5

1) 1) "count"
   2) (integer) 214
   3) "reason"
   4) "auth"
   5) "username"
   6) "metrics"

ACL GETUSER metrics reveals the user is off — a cleanup script disabled it thinking it was unused. The fix is to re-enable the user with a fresh password and update the job’s secret:

redis-cli -a 'AdminPass' ACL SETUSER metrics on '>NewMetricsPass' '~metrics:*' '+@read'
redis-cli -a 'AdminPass' ACL LIST | grep metrics
# Update the client secret, then reload the job
sudo systemctl restart reporting-job

After the restart the job authenticates cleanly. Longer term the ACL rules moved into an aclfile under config management (with CONFIG REWRITE) so no ad-hoc script can disable a live user again.

Prevention Best Practices

• Rotate passwords atomically: update the server and every consuming client from one managed secret so no client is ever left on the old value.
• Define ACL users declaratively in an aclfile under version control; avoid ad-hoc ACL SETUSER on live nodes.
• Use ACL LOG as your first stop — it names the failing username and reason without leaking secrets.
• Keep least-privilege ACL users per service (+@read, key patterns) rather than sharing one credential.
• Alert on a spike in WRONGPASS/auth failures; it can indicate a bad deploy or a brute-force attempt.
• Never disable a user without confirming it is unreferenced; grep client configs first.
• Feed the ACL LOG output into the free incident assistant, and see more Redis guides.

Quick Command Reference

# Which auth model?
grep -E '^requirepass|^user |^aclfile' /etc/redis/redis.conf

# Test the exact credential
redis-cli -h <HOST> --user app --pass '<PASS>' PING 2>/dev/null
redis-cli -h <HOST> -a '<PASS>' PING 2>/dev/null

# Inspect the user and recent failures
redis-cli -a '<ADMIN_PASS>' ACL GETUSER app
redis-cli -a '<ADMIN_PASS>' ACL LIST
redis-cli -a '<ADMIN_PASS>' ACL LOG 10

# Fix a disabled user / set a password
redis-cli -a '<ADMIN_PASS>' ACL SETUSER app on '>newpass' '~app:*' '+@all'
redis-cli -a '<ADMIN_PASS>' CONFIG REWRITE

Conclusion

WRONGPASS invalid username-password pair or user is disabled means a credential was sent and rejected. The deliberately vague message covers three cases:

1. A wrong or stale password (most often after a rotation).
2. An ACL user that exists but is disabled (off).
3. A wrong or non-existent username.

Use ACL LOG to see exactly which username failed and why, verify the correct credential with a direct redis-cli login, and fix the client secret or re-enable the user. Distinguish it from NOAUTH (no credential sent) so you know whether the client is sending the wrong secret or no secret at all.