Hitting the authentication wall
Connecting your application to a Redis server should result in a simple PONG response. Instead, you might encounter a frustrating brick wall: the WRONGPASS error. It looks like this:
WRONGPASS invalid username-password pair or user is disabled.
This specific error message appeared with the release of Redis 6.0. If you are accustomed to older versions where a single requirepass directive handled everything, this multi-user behavior can be confusing. It means the credentials provided don't match any entry in the Access Control List (ACL), or the specific account you are targeting is currently deactivated.
Why this happens in Redis 6+
Before version 6.0, Redis authentication was a simple binary check: you either had the global password or you didn't. Redis 6 introduced ACLs (Access Control Lists), bringing granular permissions and multiple user support to the database. Even if you don't think you are using ACLs, Redis 6+ manages the legacy requirepass system by mapping it to a default user.
When WRONGPASS triggers, one of these three scenarios is usually the culprit:
- The Missing Username: Your client is only sending a password, but the server expects a username (usually
default) to validate the request. - Credential Mismatch: You have a typo in the username or password for a specific ACL account.
- Account Deactivation: The user exists in the ACL table but is explicitly set to
off.
Step 1: Debug with redis-cli
Bypass your application code and go straight to the source. Using the command-line interface (CLI) directly on the server helps determine if the issue lies in your configuration or your application's connection string.
Try authenticating manually as the default user on port 6379:
redis-cli
> AUTH default your_password_here
A successful login returns OK. If you still see WRONGPASS, the issue is definitely on the server-side configuration.
Step 2: Inspecting the ACL list
If you can log in via a local connection (which often bypasses AUTH depending on your protected-mode settings), check the status of your users. Run the following command:
redis-cli
> ACL LIST
Look closely at the default user entry. It typically looks like this:
user default on nopass ~* &* +@all
If you see off, the user is disabled. If you see a string like >9f86d..., a password is required. If the configuration doesn't match what you expect, check your redis.conf or external users.acl file.
Step 3: Fix the 'Default' user configuration
In modern Redis environments, requirepass acts as a shortcut for the default user's password. Many developers encounter errors when an upgrade causes these settings to conflict. Locate your redis.conf (often found in /etc/redis/) and verify this line:
requirepass your_strong_password
To fix a locked-out default user immediately via the CLI (assuming you have admin access), use this command:
ACL SETUSER default on >your_strong_password +@all ~*
Step 4: Using dedicated users (Recommended)
Relying on the default user for every service is a security risk. Best practice dictates creating specific accounts for different applications to limit potential damage from a credential leak.
Create a dedicated app_user with access to all keys and commands like this:
ACL SETUSER app_user on >another_secure_password +@all ~*
Update your application to use both the username and password. While older Redis libraries only accepted a password string, modern drivers require both for ACL compatibility.
Example: Connection string format
Modern connection strings for libraries like redis-py or ioredis should follow this URI format:
redis://app_user:another_secure_password@localhost:6379
Security and Persistence Tips
Weak passwords are often "fixed" by admins who forget to update the application, leading to WRONGPASS errors. Secure configurations start with high-entropy strings. For generating these, tools like the Password Generator on ToolCraft are excellent because they run locally in your browser, ensuring your secrets aren't logged on a remote server.
Finally, ensure your changes survive a reboot. If you modified users via redis-cli, they will vanish when the service restarts unless you persist them. If you use an external ACL file, run:
ACL SAVE
Note: This command only works if an aclfile path is defined in redis.conf. If you use inline configuration, you must manually update the redis.conf file to make changes permanent.
Final Verification
Confirm the fix by logging in with your new credentials and testing a basic command:
redis-cli
> AUTH app_user another_secure_password
OK
> PING
PONG
Seeing that PONG means you have successfully navigated the ACL system and resolved the WRONGPASS error.