ERR unknown command '…', with args beginning with

What it means

Redis looked up the first word you sent in its table of commands and didn’t find it. It refuses with ERR unknown command, quoting the name and the start of the arguments (about the first 128 characters), and runs nothing:

(error) ERR unknown command 'HGETAL', with args beginning with: 'seo:err:h' 

Capitals don’t matter: get, GET and Get are the same command. The name itself is one this server doesn’t have, because it’s misspelt, newer than the server, part of a module that isn’t loaded, or removed by the server’s configuration.

Related forms of the same problem:

• A subcommand it doesn’t know. CLIENT, CONFIG, OBJECT, XINFO and other container commands take a second word; a wrong one gets ERR unknown subcommand 'FOO'. Try CLIENT HELP.
• Inside a Lua script, redis.call('nosuch') fails with ERR Unknown Redis command called from script (Valkey: Unknown command called from script).
• Inside a transaction, the unknown command is refused as you queue it, and EXEC then throws the whole transaction away with EXECABORT.
• Not to be confused with NOPERM: a command that exists but your ACL user may not run gets NOPERM instead.

Common causes

1. A typo: HGETAL for HGETALL, STE for SET, DELL for DEL.
2. A command newer than the server. Every command has a version it first appeared in: GETDEL and GETEX in Redis 6.2, LMPOP in 7.0, HEXPIRE in 7.4, HGETEX and HGETDEL in 8.0. Valkey 8.1 has none of the hash field expiry commands; Valkey added hash field expiration in 9.0. Code written for a recent Redis and run against an older server, or against Valkey 8, fails this way. A client that opens with HELLO (to ask for RESP3) gets it from Redis 5 and older, which don’t have HELLO.
3. A module command without the module: JSON.SET and JSON.GET (JSON), FT.CREATE and FT.SEARCH (search), BF.ADD (Bloom filters), TS.ADD (time series). The official redis:8 Docker image loads these modules. A plain Valkey server has none of them; Valkey ships its JSON, search and Bloom modules in a separate image, valkey/valkey-bundle.
4. A command renamed or disabled by configuration. rename-command CONFIG "" in redis.conf removes CONFIG completely; renaming it to another word hides it under that name. Managed services restrict administrative commands: on ElastiCache, CONFIG, SAVE, BGSAVE, BGREWRITEAOF, DEBUG, MIGRATE, REPLICAOF, SHUTDOWN and SYNC aren’t available.
5. Something that isn’t a Redis command: an SQL statement (INSERT INTO …), a line copied with its prompt (127.0.0.1:6379> GET x), or redis-cli GET x typed inside redis-cli.

How to fix it

Check the name, and whether this server has it

COMMAND INFO <name>
COMMAND DOCS <name>
COMMAND LIST FILTERBY PATTERN 'hget*'

COMMAND INFO replies (nil) for a command the server doesn’t have. COMMAND DOCS includes since, the version that added it, and COMMAND LIST FILTERBY PATTERN lists the commands whose names match, which helps with typos. Then check what you’re connected to:

redis-cli INFO server | grep -E '^(redis_version|server_name|valkey_version):'

Valkey reports redis_version:7.2.4 for compatibility; its own version is in valkey_version.

Use a command the server has, or upgrade it

If the command is newer than the server, either upgrade the server or write the same thing with older commands: GET then DEL inside MULTI … EXEC instead of GETDEL, for example. Hash field expiry needs Redis 7.4 or later (8.0 for HGETEX and HSETEX), or Valkey 9.0, which added hash field expiration; on older servers, keep fields that need their own expiry in separate keys with a TTL.

Load the module, or use a server that has it

MODULE LIST shows what’s loaded. If JSON.* or FT.* commands are unknown, the server needs the module: on Redis, the official Redis 8 image includes them; on Valkey, use the valkey/valkey-bundle image or load the modules with loadmodule in its configuration. On a hosted service, check which modules your plan includes.

Find out whether the command was renamed or blocked

If you run the server, look for rename-command lines in its configuration file. On a managed service, use the provider’s own way of doing the job: on ElastiCache, parameter groups instead of CONFIG SET and its backups instead of BGSAVE.

Reproduce it

Redis 8.10.2 and Valkey 8.1.10, redis-cli in database 15. Both servers gave:

FOO bar baz
(error) ERR unknown command 'FOO', with args beginning with: 'bar' 'baz' 
HGETAL seo:err:h
(error) ERR unknown command 'HGETAL', with args beginning with: 'seo:err:h' 
CLIENT FOO
(error) ERR unknown subcommand 'FOO'. Try CLIENT HELP.

A command with no arguments differed: Redis printed ERR unknown command 'foo', and Valkey printed ERR unknown command 'foo', with args beginning with: with nothing after it. On Redis, a line sent with its prompt pasted in front, and an SQL statement:

127.0.0.1:6379> GET seo:err:x
(error) ERR unknown command '127.0.0.1:6379>', with args beginning with: 'GET' 'seo:err:x' 
INSERT INTO users VALUES (1)
(error) ERR unknown command 'INSERT', with args beginning with: 'INTO' 'users' 'VALUES' '(1)' 

Versions and modules. The Redis server had the search, JSON, Bloom and time series modules loaded, so JSON.GET seo:err:doc replied (nil) and HEXPIRE ran (replying -2: no such key). On Valkey 8.1.10:

JSON.GET seo:err:doc
(error) ERR unknown command 'JSON.GET', with args beginning with: 'seo:err:doc' 
HEXPIRE seo:err:h 60 FIELDS 1 f
(error) ERR unknown command 'HEXPIRE', with args beginning with: 'seo:err:h' '60' 'FIELDS' '1' 'f' 
COMMAND INFO hexpire
1) (nil)

On Redis, COMMAND DOCS hexpire gave "since" "7.4.0".

In a transaction, on Redis:

MULTI
OK
SET seo:err:a 1
QUEUED
STE seo:err:b 2
(error) ERR unknown command 'STE', with args beginning with: 'seo:err:b' '2' 
EXEC
(error) EXECABORT Transaction discarded because of previous errors.
EXISTS seo:err:a
(integer) 0

A temporary Redis 8.10.2 container started with two commands renamed away:

docker run --rm -d --name seo-err-renamed redis:8 redis-server --rename-command CONFIG "" --rename-command FLUSHALL ""

CONFIG GET maxmemory
(error) ERR unknown command 'CONFIG', with args beginning with: 'GET' 'maxmemory' 
FLUSHALL
(error) ERR unknown command 'FLUSHALL'

From a script, EVAL "return redis.call('nosuch')" 0:

(error) ERR Unknown Redis command called from script script: 206396248e12c6e742fd7296250433c8d7343b74, on @user_script:1.

Valkey worded it ERR Unknown command called from script.

In Inlet

Query tabs take redis-cli commands, one a line, and complete command names as you type, so you can pick the right name before you run it. COMMAND INFO, MODULE LIST and INFO server run there too, and INFO shows as a table. When the server refuses a command, Inlet shows its message and links to this page.