Fix Redis 'ERR unknown command' Error — Command Not Found or Blocked

The Error

You run a Redis command and the server spits back:

(error) ERR unknown command 'COMMAND_NAME', with args beginning with: ...

Or the shorter variant:

(error) ERR unknown command 'LMPOP'

Redis has no idea what that command is. Either it doesn't exist in your server's version, it was disabled in config, or an ACL rule is silently blocking it for your user.

Root Causes

• Version mismatch — you're calling a command added in Redis 6.2 or 7.x but your server is older.
• ACL restriction — Redis 6+ ACL rules can block specific commands per user. The error looks identical to "command not found," which trips a lot of people up.
• rename-command in redis.conf — the command was renamed or disabled in config, common on shared or managed Redis instances.
• Module not loaded — commands like JSON.GET (RedisJSON) require a module that isn't loaded.
• Typo — plain misspelling of the command name.

Step 1 — Check Your Redis Version

Version mismatch is the most common culprit. Run this on the server:

redis-cli INFO server | grep redis_version

Example output:

redis_version:6.0.16

Then check when the command you need was actually introduced:

• LMPOP, ZMPOP — Redis 7.0
• GETDEL, GETEX — Redis 6.2
• OBJECT FREQ — Redis 4.0
• WAIT — Redis 3.0

Running 6.0 and trying to use LMPOP? That's your problem right there. Upgrade Redis or switch to an equivalent command that works on your current version.

Upgrading Redis (Ubuntu/Debian)

sudo add-apt-repository ppa:redislabs/redis
sudo apt-get update
sudo apt-get install redis

Upgrading Redis (macOS)

brew upgrade redis
brew services restart redis

Step 2 — Check ACL Rules (Redis 6+)

Redis 6 added ACL (Access Control Lists). Here's the tricky part: when an ACL rule blocks a command, the error says "unknown command" — not "permission denied." It looks exactly like the command doesn't exist, which makes it genuinely confusing to debug.

Check what your current user is allowed to do:

redis-cli ACL WHOAMI
redis-cli ACL LIST

A restricted user looks like this:

"user app on >password ~* &* -@all +get +set +del"

-@all blocks every command. Only GET, SET, and DEL are explicitly allowed. Call anything else and you'll get the "unknown command" error.

Fix — Grant the Specific Command

redis-cli ACL SETUSER app +hset +hget +hgetall

Or grant an entire category — for example, all hash commands at once:

redis-cli ACL SETUSER app +@hash

To give a user full access (use with caution in production):

redis-cli ACL SETUSER app +@all

Persist ACL Changes

ACL changes made via redis-cli are in-memory only — they disappear on restart. Save them:

redis-cli ACL SAVE

Or define them permanently in redis.conf using a dedicated ACL file:

aclfile /etc/redis/users.acl

Step 3 — Check rename-command in redis.conf

Hosted Redis providers (and cautious sysadmins) often disable dangerous commands like FLUSHALL or CONFIG using the rename-command directive. This is standard practice on shared instances. Check if it's affecting your command:

grep -i rename-command /etc/redis/redis.conf

Typical output on a locked-down instance:

rename-command FLUSHALL ""
rename-command CONFIG ""

An empty string completely disables the command. Two ways forward:

• Use the renamed version of the command, if it was renamed rather than deleted.
• Remove or update the rename-command line and restart Redis.

Restart Redis After Config Change

# systemd
sudo systemctl restart redis

# macOS
brew services restart redis

Step 4 — Check If a Module Is Required

Some Redis commands only exist when a module is loaded. JSON.GET, for instance, is part of RedisJSON — without it loaded, you get:

127.0.0.1:6379> JSON.GET mykey
(error) ERR unknown command 'JSON.GET'

Check what's currently loaded on your server:

redis-cli MODULE LIST

Empty list, or missing the module you need? Add it to redis.conf:

loadmodule /usr/lib/redis/modules/librejson.so

To load at runtime without restarting (temporary — won't survive a restart):

redis-cli MODULE LOAD /path/to/module.so

Step 5 — Rule Out a Typo

Worth a quick sanity check before going further. Common mix-ups:

• SETEX vs SETPX — one takes seconds, the other milliseconds, easy to swap
• SRANDMEMBER — frequently misspelled
• ZADD with NX/XX subcommands — only supported from Redis 3.0.2

Check a command's exact syntax straight from Redis itself:

redis-cli COMMAND DOCS ZADD

Or list everything your server supports:

redis-cli COMMAND COUNT
redis-cli COMMAND

Verification

Once you've applied a fix, test the command directly:

redis-cli -u redis://localhost:6379 LMPOP 1 mylist LEFT

For ACL fixes, confirm the user now has the right permissions:

redis-cli ACL GETUSER app

The command or its category should now appear in the commands field of the output.

Prevention

• Pin your Redis version in your infrastructure config — Ansible, Terraform, Docker image tags — so dev and prod always run the same thing. Version drift between environments is how most "works on my machine" Redis bugs happen.
• Test ACL rules in staging first. Create a minimal-privilege user there, run through all the commands your app actually uses, and verify nothing is blocked before pushing to production.
• Document any rename-command entries. Future engineers will waste hours debugging "missing" commands if there's no runbook note explaining why FLUSHALL seems to not exist.
• Lock local dev to a specific Redis version: docker run --rm redis:7.2 redis-cli --version gives you a clean, versioned environment with no surprises.

Working with Redis config files? ToolCraft's YAML ↔ JSON Converter can catch syntax errors in your deployment configs before you apply them — everything runs locally, nothing gets uploaded.