Repository navigation
Redis compat: Binary (non-UTF-8) keys rejected: "ERR key must be valid UTF-8" #437
Description
What differs
The command (with its arguments), or the client library and the call you made.
python3 -c 'import redis; r=redis.Redis(port=6380); print(r.execute_command("SET", b"\xff\x00k", b"1", "NX", "EX", 30))'
Same for GET, INCRBY and EVAL with binary KEYS.
What Redis or Valkey returns
Valkey 9.1.3: OK (keys are binary-safe).
KiviDB: ERR key must be valid UTF-8 (SET), ERR must be valid UTF-8 (GET, INCRBY, EVAL).
Where it matters
Stalwart Mail Server. Its Redis in-memory store uses binary keys for locks, rate limits and sessions. On KiviDB the mail queue, SMTP submission, POP3 and JMAP all fail.
Environment
- KiviDB version (
INFO server,kividb_version) and variant: 1.2.0, full - How it runs: Docker image
docker.io/kividb/kividb:v1.2.0-full(Kubernetes)
Activity
murtazayusuf commentedon Nov 5, 2026
Thanks, @wuast94, and for the exact repro and the Stalwart context. Confirmed. KiviDB stores keys as UTF-8 strings (
Key = CompactString,src/store/mod.rs), and about 270 places across the command handlers reject non-UTF-8 input with that error. Redis and Valkey keys are binary-safe, so this is a real compatibility gap. It's now listed indocs/COMPATIBILITY.md(#438).Making keys, and with them hash fields and set members, binary-safe (values and sorted-set members already are) means changing the key type throughout the engine, not a one-line fix. We'll scope it and report back here.
Until then, there's no server-side workaround. A client that can encode its keys (for example hex or base64) would avoid it, but Stalwart doesn't offer that, so Stalwart needs Redis or Valkey for now.
Merge pull request #438 from kividbio/docs/437-utf8-keys
Merge pull request #460 from kividbio/binkeys/1-types
Merge pull request #490 from kividbio/binkeys/2-plumbing
Keys as bytes everywhere the keyspace is read back
Keys, stream names and vector-set elements of any bytes (#437, step 3)
Cluster FT.SEARCH gives back other masters' keys as their bytes