Sửa lỗi Redis 'ERR unknown command' — Lệnh Không Tìm Thấy hoặc Bị Chặn

Lỗi Là Gì

Bạn chạy một lệnh Redis và server trả về:

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

Hoặc dạng ngắn hơn:

(error) ERR unknown command 'LMPOP'

Redis không nhận ra lệnh đó. Có thể lệnh không tồn tại trong phiên bản server bạn đang dùng, bị tắt trong config, hoặc một quy tắc ACL đang âm thầm chặn lệnh đó với user của bạn.

Nguyên Nhân Gốc Rễ

Sai phiên bản — bạn đang gọi một lệnh được thêm vào Redis 6.2 hoặc 7.x nhưng server đang chạy phiên bản cũ hơn.
Bị chặn bởi ACL — Redis 6+ có thể dùng ACL để chặn từng lệnh cụ thể theo từng user. Lỗi trông y hệt "lệnh không tồn tại," điều này khiến rất nhiều người bị nhầm lẫn.
rename-command trong redis.conf — lệnh bị đổi tên hoặc bị vô hiệu hóa trong config, thường gặp trên các Redis instance dùng chung hoặc được quản lý.
Module chưa được load — các lệnh như JSON.GET (RedisJSON) yêu cầu một module chưa được tải.
Gõ nhầm — đơn giản là viết sai tên lệnh.

Bước 1 — Kiểm Tra Phiên Bản Redis

Sai phiên bản là nguyên nhân phổ biến nhất. Chạy lệnh này trên server:

redis-cli INFO server | grep redis_version

Ví dụ kết quả:

redis_version:6.0.16

Sau đó kiểm tra lệnh bạn cần được giới thiệu từ phiên bản nào:

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

Đang chạy 6.0 mà lại dùng LMPOP? Đó chính là vấn đề. Hãy nâng cấp Redis hoặc chuyển sang lệnh tương đương hoạt động trên phiên bản hiện tại.

Nâng Cấp Redis (Ubuntu/Debian)

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

Nâng Cấp Redis (macOS)

brew upgrade redis
brew services restart redis

Bước 2 — Kiểm Tra ACL Rules (Redis 6+)

Redis 6 đã bổ sung ACL (Access Control Lists). Điểm khó chịu ở đây là: khi một quy tắc ACL chặn một lệnh, lỗi trả về là "unknown command" — không phải "permission denied." Trông y hệt như lệnh không tồn tại, khiến việc debug thực sự rất khó chịu.

Kiểm tra user hiện tại của bạn được phép làm gì:

redis-cli ACL WHOAMI
redis-cli ACL LIST

Một user bị hạn chế trông như thế này:

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

-@all chặn mọi lệnh. Chỉ có GET, SET, và DEL được cho phép rõ ràng. Gọi bất kỳ lệnh nào khác và bạn sẽ nhận được lỗi "unknown command".

Cách Sửa — Cấp Quyền Cho Lệnh Cụ Thể

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

Hoặc cấp quyền cho cả một nhóm lệnh — ví dụ, tất cả lệnh hash cùng lúc:

redis-cli ACL SETUSER app +@hash

Để cấp toàn quyền cho user (cẩn thận khi dùng trên môi trường production):

redis-cli ACL SETUSER app +@all

Lưu Thay Đổi ACL

Các thay đổi ACL qua redis-cli chỉ tồn tại trong bộ nhớ — sẽ mất khi restart. Lưu lại bằng lệnh:

redis-cli ACL SAVE

Hoặc định nghĩa cố định trong redis.conf bằng file ACL riêng:

aclfile /etc/redis/users.acl

Bước 3 — Kiểm Tra rename-command Trong redis.conf

Các nhà cung cấp Redis hosted (và các sysadmin thận trọng) thường vô hiệu hóa các lệnh nguy hiểm như FLUSHALL hay CONFIG bằng chỉ thị rename-command. Đây là thực hành phổ biến trên các instance dùng chung. Kiểm tra xem nó có ảnh hưởng đến lệnh của bạn không:

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

Kết quả điển hình trên một instance bị khóa chặt:

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

Chuỗi rỗng sẽ vô hiệu hóa hoàn toàn lệnh đó. Có hai hướng giải quyết:

Dùng tên đã được đổi của lệnh, nếu nó được đổi tên thay vì xóa đi.
Xóa hoặc cập nhật dòng rename-command rồi restart Redis.

Restart Redis Sau Khi Thay Đổi Config

# systemd
sudo systemctl restart redis

# macOS
brew services restart redis

Bước 4 — Kiểm Tra Xem Có Cần Load Module Không

Một số lệnh Redis chỉ hoạt động khi có module được load. Ví dụ JSON.GET là một phần của RedisJSON — nếu chưa load module đó, bạn sẽ gặp:

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

Kiểm tra những module đang được load trên server:

redis-cli MODULE LIST

Danh sách trống, hoặc thiếu module bạn cần? Thêm vào redis.conf:

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

Để load lúc đang chạy mà không cần restart (tạm thời — sẽ mất sau khi restart):

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

Bước 5 — Loại Trừ Lỗi Gõ Nhầm

Đáng kiểm tra nhanh trước khi đi sâu hơn. Những nhầm lẫn thường gặp:

SETEX vs SETPX — một cái tính giây, cái kia tính mili giây, dễ nhầm lắm
SRANDMEMBER — hay bị viết sai
ZADD với subcommand NX/XX — chỉ hỗ trợ từ Redis 3.0.2

Kiểm tra cú pháp chính xác của một lệnh ngay từ Redis:

redis-cli COMMAND DOCS ZADD

Hoặc liệt kê tất cả lệnh server bạn hỗ trợ:

redis-cli COMMAND COUNT
redis-cli COMMAND

Kiểm Tra Lại

Sau khi áp dụng cách sửa, hãy test trực tiếp lệnh đó:

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

Với các sửa lỗi ACL, xác nhận user đã có quyền phù hợp:

redis-cli ACL GETUSER app

Lệnh hoặc nhóm lệnh giờ sẽ xuất hiện trong trường commands của kết quả trả về.

Phòng Ngừa

Ghim phiên bản Redis trong config hạ tầng của bạn — Ansible, Terraform, Docker image tags — để môi trường dev và production luôn chạy cùng phiên bản. Sự chênh lệch phiên bản giữa các môi trường là nguồn gốc của hầu hết các lỗi Redis kiểu "chạy được trên máy tôi".
Kiểm tra ACL rules trên staging trước. Tạo một user với quyền tối thiểu ở đó, chạy qua tất cả các lệnh mà ứng dụng thực sự sử dụng, và xác nhận không có gì bị chặn trước khi đẩy lên production.
Ghi chú lại các dòng rename-command. Các kỹ sư sau này sẽ mất hàng giờ debug các lệnh "không tồn tại" nếu không có ghi chú nào giải thích tại sao FLUSHALL có vẻ không tồn tại.
Khóa môi trường dev local vào một phiên bản Redis cụ thể: docker run --rm redis:7.2 redis-cli --version cho bạn một môi trường sạch, có phiên bản xác định, không có bất ngờ nào.

Đang làm việc với file config Redis? YAML ↔ JSON Converter của ToolCraft có thể phát hiện lỗi cú pháp trong config deployment của bạn trước khi áp dụng — tất cả chạy cục bộ, không có gì được tải lên.