🚨 Redis Error Guide: 'ERR syntax error' — Fix Invalid Command Options and Flags

Overview

Redis returns syntax error when a command has the right number of arguments but one of the optional tokens is unrecognized, out of order, or unsupported by this server version. Unlike wrong number of arguments, the arity is fine — Redis got a flag or option it could not parse.

The literal error clients receive:

(error) ERR syntax error

The classic trigger is a modifier the running Redis version does not support (for example SET key val KEEPTTL on Redis 5, or GET on SET before Redis 6.2), or two mutually exclusive flags used together (EX and PX, or NX and XX).

Symptoms

• A command works without its options but fails once you add a flag.
• The error is generic (syntax error) with no hint about which token.
• Frequently appears after a Redis downgrade, or against a managed/older server.

redis-cli SET session:1 payload KEEPTTL

(error) ERR syntax error

Common Root Causes

1. Flag not supported by this Redis version

KEEPTTL (SET) arrived in 6.0; the GET option on SET in 6.2; EXAT/PXAT in 6.2. Older servers reject them.

redis-cli INFO server | grep redis_version

redis_version:5.0.7

2. Mutually exclusive options combined

redis-cli SET k v EX 10 PX 10000   # EX and PX together
redis-cli SET k v NX XX             # NX and XX together

Both raise syntax error.

3. Options in the wrong position or mistyped

redis-cli SET k v 10 EX      # value/flag order swapped
redis-cli EXPIRE k 60 XY     # 'XY' is not a valid EXPIRE flag

4. A stray or duplicated token

An extra flag left in by string-building code, or a duplicated EX, trips the parser.

How to diagnose

Step 1: Strip the command back to its minimum

Remove all optional flags and re-run; if it succeeds, add flags back one at a time.

redis-cli SET session:1 payload          # works
redis-cli SET session:1 payload EX 60    # add one flag

Step 2: Confirm the server version supports the flag

redis-cli INFO server | grep redis_version

Cross-check the flag against the version that introduced it.

Step 3: See the exact wire command

redis-cli MONITOR

1720780500.1 [0 127.0.0.1:5555] "SET" "k" "v" "EX" "10" "PX" "10000"

MONITOR shows the real token stream — here two conflicting expiry flags. Run it only briefly; it adds load to the server.

Step 4: Check for mutually exclusive combinations

Review the command’s documentation for flags that cannot coexist (EX/PX/EXAT/PXAT, NX/XX).

Fixes

Use a flag your version supports

# On Redis < 6.0, emulate KEEPTTL by reading the TTL first, or upgrade
redis-cli TTL session:1
redis-cli SET session:1 payload EX 60

Pick one option from an exclusive group

redis-cli SET k v EX 10        # seconds
# or
redis-cli SET k v PX 10000     # milliseconds — not both

Correct the option order

redis-cli SET k v EX 60 NX

Remove stray tokens in client code

Build the option list explicitly rather than concatenating strings, so a leftover flag cannot slip in.

What to watch out for

• Managed Redis (ElastiCache, MemoryDB, Azure Cache) may run an older engine than your local dev box, so a flag that works locally fails in production. Pin your dev version to match.
• syntax error never names the bad token; bisecting flags is the fastest way to isolate it.
• Some client libraries silently add flags (for example GET on SET for getset emulation); an upgrade can change what they emit.
• After a failed SET ... GET, remember the GET-on-SET option requires Redis 6.2+.

Related

• Redis Error: ‘ERR wrong number of arguments for command’
• Redis Error: ‘ERR invalid expire time in set command’
• Redis Error: ‘ERR unknown command’ (module not loaded)

Paste the failing command into the free incident assistant, and browse more Redis guides.