🚨 Redis Error Guide: 'ERR unknown command' — Fix Missing Modules and Typos

Overview

Redis rejects a command it does not recognize on the server that received it. The message quotes the command and the first few arguments:

ERR unknown command 'JSON.SET', with args beginning with: 'user:42', '$', '{"name":"Ada"}'

The same error covers a plain typo or a command your Redis version does not have:

ERR unknown command 'GTE', with args beginning with: 'key', '10'

And a command that was disabled or renamed via configuration:

ERR unknown command 'FLUSHALL', with args beginning with:

The single most common cause in modern stacks is a module command (JSON.*, FT.*, TS.*, BF.*, TOPK.*, CF.*) sent to a Redis server that does not have that module loaded.

Symptoms

• Module commands like JSON.SET, FT.SEARCH, TS.ADD, or BF.ADD fail with unknown command, while core commands (GET, SET) work fine.
• The command works in a local Docker image (e.g. redis/redis-stack) but fails against managed or plain redis:7 in another environment.
• A previously working command breaks after a version downgrade, an image change, or moving from Redis Stack to community Redis.
• A command fails on some cluster nodes but not others (module loaded unevenly).
• A rename/disable via rename-command in the config makes an admin command “vanish.”

Common Root Causes

• Module not loaded — JSON.*/FT.*/TS.*/BF.* require RedisJSON, RediSearch, RedisTimeSeries, or RedisBloom. Plain community Redis does not ship them; the server literally has no such command.
• Wrong image or server — code expected redis/redis-stack (modules bundled) but connected to plain redis, or to a managed instance where modules aren’t enabled.
• Version too old — a core command (OBJECT FREQ, COPY, GETDEL, SINTERCARD) that exists only in a newer Redis than the server is running.
• Typo or wrong subcommand — GTE instead of GET, or CLIENT NOEVICT on a version that lacks it.
• Command renamed or disabled — rename-command FLUSHALL "" (disabled) or renamed to an obscure string for safety; the original name is now unknown.
• Sent to the wrong service entirely — the connection points at a non-Redis or RESP-incompatible endpoint.

Diagnostic Workflow

First, confirm which command was rejected and check for a simple typo against the command list:

# Does the server know this command at all? (empty output = unknown)
redis-cli COMMAND INFO JSON.SET
redis-cli COMMAND INFO GET        # compare with one you know works

If it is a module command, list the modules actually loaded on the server you’re connected to:

# Which modules are loaded here?
redis-cli MODULE LIST
# Look for: name "ReJSON", "search", "timeseries", "bf" ...

Empty or missing module output is the smoking gun. Confirm you’re on the server and version you think you are:

redis-cli INFO server | grep -E 'redis_version|redis_mode|os|executable'
redis-cli INFO server | grep redis_version    # is the command new enough?

Check whether the command was renamed or disabled in config:

# Search the running config / files for rename-command directives
redis-cli CONFIG GET save   # (CONFIG GET can't read rename-command; check the file)
grep -R 'rename-command' /etc/redis/ 2>/dev/null

For clusters, verify the module is loaded on every node, not just the one you tested:

redis-cli -c CLUSTER NODES | awk '{print $2}' | cut -d@ -f1 | while read addr; do
  echo "== $addr =="
  redis-cli -h "${addr%:*}" -p "${addr##*:}" MODULE LIST
done

Example Root Cause Analysis

A service used JSON.SET and JSON.GET to store user documents. It worked perfectly in local development but every write failed in staging with:

ERR unknown command 'JSON.SET', with args beginning with: 'user:42', '$', ...

MODULE LIST against the staging instance returned an empty array — no modules at all. INFO server showed the difference: local development ran the redis/redis-stack-server image (RedisJSON bundled), while staging had been provisioned with the plain redis:7.2 image. The command wasn’t a typo and wasn’t version-gated core Redis — the module simply wasn’t present.

Two fixes were viable. For self-hosted staging, switch to the Stack image (or load the module explicitly):

# Option A: run the image that bundles the modules
docker run -d --name redis redis/redis-stack-server:latest

# Option B: load the module into a plain server (self-hosted only)
#   redis.conf:  loadmodule /opt/redis-stack/lib/rejson.so
redis-cli MODULE LOAD /opt/redis-stack/lib/rejson.so
redis-cli MODULE LIST     # confirm "ReJSON" now appears

The team standardized every environment on the Stack image so local, staging, and production shared the same module set — eliminating the “works on my machine” gap. (On a managed provider, the equivalent fix is enabling the module in the provider’s console, since MODULE LOAD is typically blocked there.)

Prevention Best Practices

• Pin the same Redis distribution everywhere — if you use module commands, run redis-stack (or an equivalent with the modules enabled) in dev, CI, staging, and prod so MODULE LIST matches.
• Assert required modules at startup — have the app run MODULE LIST on boot and fail fast with a clear message if ReJSON/search/timeseries/bf is missing, rather than erroring per request.
• Check minimum Redis version for any newer core command you rely on (COPY, GETDEL, SINTERCARD, OBJECT FREQ) and gate on redis_version.
• Document rename-command/disabled commands — keep security renames in version control so an “unknown command” on an admin op is expected, not a mystery.
• Load modules on every cluster node and verify uniformly; uneven module loading causes commands to work on some slots and fail on others.
• Validate the endpoint — make sure the connection string points at a real Redis (and the right one), not a look-alike or a different service.

Quick Command Reference

redis-cli COMMAND INFO JSON.SET        # empty = command not known here
redis-cli COMMAND COUNT                # how many commands this server knows
redis-cli MODULE LIST                  # loaded modules (ReJSON, search, ...)
redis-cli INFO server | grep redis_version   # is a core command new enough?
redis-cli MODULE LOAD /path/to/module.so     # self-hosted: load a module
grep -R 'rename-command' /etc/redis/          # find renamed/disabled commands

# Cluster: check modules on every node
redis-cli -c CLUSTER NODES | awk '{print $2}' | cut -d@ -f1

Conclusion

ERR unknown command means the server that received the request has no such command — and in modern deployments that is usually a missing module (JSON.*, FT.*, TS.*, BF.*) sent to a plain Redis instead of a Stack/module-enabled one, not a typo. MODULE LIST and INFO server settle it in seconds: confirm the module is loaded and the version is new enough on the exact server (and every cluster node) you’re talking to. The durable fix is environment parity — run the same Redis distribution with the same modules everywhere, and assert required modules at startup so the failure is a clear boot-time error instead of a runtime surprise.