Claude Code bị lỗi, không chạy? 5 nhóm lỗi thường gặp & cách khắc phục nhanh (2026)

Claude Code cập nhật khá nhanh nên tên lệnh/hành vi có thể đổi; mình sẽ ghi chú khi một chi tiết cần bạn tự kiểm tra lại. Đối chiếu với tài liệu chính thức của Claude Code khi cần chắc chắn.

Bảng tra lỗi nhanh (triệu chứng → cách fix)

Đây là phần tra cứu chính. Tìm đúng dòng khớp thông báo bạn đang thấy, làm theo cột cuối, và bấm sang mục chi tiết nếu cần hiểu nguyên nhân.

Trước khi sửa: lỗi của bạn hay của Anthropic?

Sai lầm phổ biến nhất của người mới là lao vào cài lại, đổi config trong khi lỗi thực ra nằm ở phía server. Trước mỗi lần sửa, dành 30 giây phân loại:

• Lỗi phía bạn (env/config): command not found, PATH sai, auth hỏng, permission chặn, context đầy. Đặc điểm: lặp lại đều đặn, cùng một thông báo mỗi lần chạy.
• Lỗi phía Anthropic (không tự fix được): báo overloaded, model không phản hồi dù mạng ổn, lỗi xuất hiện đột ngột dù bạn không đổi gì. Đặc điểm: bất chợt, thường tự hết sau ít phút.

Ba lệnh phân loại nhanh: claude --version (đã cài đúng chưa) → /status (đang dùng route nào, còn quota không) → mở trang status chính thức của Anthropic (có sự cố hệ thống không). Nếu ba cái này ổn mà vẫn lỗi thì mới đến lượt sửa môi trường máy.

Lỗi 1 - Cài xong nhưng claude không chạy (command not found / PATH)

Triệu chứng. Bạn cài xong nhưng gõ claude thì gặp một trong các thông báo:

# macOS / Linux (zsh, bash)
zsh: command not found: claude

# Windows (PowerShell / CMD)
claude : The term 'claude' is not recognized as the name of a cmdlet...

Điều oái oăm: npm báo cài thành công, nhưng terminal vẫn không tìm thấy lệnh.

Nguyên nhân. Gói được cài vào thư mục global bin của npm, nhưng thư mục đó chưa nằm trong biến môi trường PATH, nên shell không biết đường tới file claude. Trên Windows, biến môi trường vừa set trong một cửa sổ thường mất khi bạn mở cửa sổ mới.

Cách fix. Đầu tiên tìm thư mục global bin của npm:

npm config get prefix
# ví dụ trả về: /Users/ban/.npm-global (macOS)
# hoặc: C:\Users\ban\AppData\Roaming\npm (Windows)

Thư mục lệnh nằm ở PREFIX/bin (macOS/Linux) hoặc chính PREFIX (Windows). Thêm nó vào PATH:

# macOS / Linux - thêm vào cuối ~/.zshrc (hoặc ~/.bashrc)
export PATH="$(npm config get prefix)/bin:$PATH"
# rồi nạp lại
source ~/.zshrc

# kiểm tra lại
claude --version

Trên Windows, mở PowerShell profile và thêm dòng tương ứng, hoặc thêm đường dẫn npm vào biến môi trường PATH của hệ thống (Settings → Environment Variables) rồi mở lại terminal. Nhưng khuyến nghị thực tế của mình: trên Windows hãy chạy Claude Code trong WSL2 thay vì PowerShell/CMD native - môi trường Linux giúp tránh gần như toàn bộ lỗi PATH và quyền lằng nhằng đặc thù của Windows.

Nếu vẫn không nhận sau khi sửa PATH, khả năng cao là bước cài ban đầu chưa sạch. Xem lại cách cài đặt Claude Code đúng chuẩn để làm lại từ đầu cho gọn.

Lỗi 2 - Không đăng nhập được / lỗi auth (API key vs subscription)

Triệu chứng. Login treo ở trình duyệt, báo unauthorized, hoặc Claude Code cứ đòi API key liên tục dù bạn nghĩ mình đã đăng nhập bằng gói Pro/Max.

Nguyên nhân. Có hai nguồn hay gây rối. Một là credential cache hỏng - token cũ còn kẹt lại. Hai, phổ biến hơn, là lẫn giữa hai route xác thực: đăng nhập bằng subscription (gói Pro/Max qua tài khoản) khác hoàn toàn với dùng ANTHROPIC_API_KEY (tính tiền theo token). Nếu bạn từng set biến môi trường ANTHROPIC_API_KEY, Claude Code có thể ưu tiên đi theo route API key và bỏ qua gói bạn đã trả tiền.

Cách fix. Reset credential trước:

claude logout
claude login # đăng nhập lại theo route bạn muốn (subscription)

Sau đó kiểm tra xem có biến API key nào đang "chen ngang" không:

# macOS / Linux
echo $ANTHROPIC_API_KEY

# Windows (PowerShell)
echo $env:ANTHROPIC_API_KEY

Nếu bạn muốn dùng gói Pro/Max mà biến này lại có giá trị, hãy xóa nó khỏi shell profile (dòng export ANTHROPIC_API_KEY=... trong .zshrc, hoặc biến môi trường trên Windows) rồi mở lại terminal. Cuối cùng chạy /status ngay trong phiên Claude Code để xác nhận đang đi đúng route. Ngược lại, nếu bạn cố ý dùng API key thì đảm bảo key còn hạn và có credit.

Lỗi 3 - "Rate limit reached" / lỗi 429

Triệu chứng. Đang chạy thì dừng giữa chừng với thông báo Rate limit reached hoặc mã 429, đôi khi dù bạn mới dùng rất ít.

Nguyên nhân. Điểm bẫy là hai hệ thống khác nhau cùng báo một câu, nhưng cách xử lý ngược nhau:

Cách fix. Đầu tiên xác định route bằng /status. Sau đó truy các process mồ côi - Claude Code đôi khi để lại tiến trình chạy ngầm sau khi bạn đóng cửa sổ, chúng vẫn đếm vào quota:

# macOS / Linux - liệt kê tiến trình claude còn sống
ps aux | grep claude
# thấy PID lạ thì tắt: kill <PID>

# Windows: mở Task Manager, tìm tiến trình node/claude còn chạy và kết thúc

Nếu route là gói subscription và bạn thật sự hết lượt, không có mẹo nào ngoài chờ cửa sổ reset hoặc tạm chuyển sang model nhẹ hơn để tiết kiệm. Với API key, việc nâng giới hạn nằm ở tier tài khoản. Muốn biết chính xác một mã 429 cụ thể xuất phát từ quy tắc nào, đối chiếu với issue trên repo anthropics/claude-code.

Lỗi 4 - Claude Code bị treo / đứng giữa chừng (context đầy)

Triệu chứng. Phiên đứng im, phản hồi chậm dần, model bắt đầu "quên" những gì bạn nói ở đầu phiên, hoặc rơi vào vòng lặp sửa tới sửa lui không kết thúc.

Nguyên nhân. Thường là context window đầy: bạn đã trò chuyện quá dài, dán vào một file khổng lồ, hoặc giao một task quá lớn trong một lượt khiến output phình to. Đây không phải lỗi server - nên đừng nhầm với overloaded phía Anthropic.

Cách fix. Theo thứ tự nhẹ đến mạnh:

• /compact - nén hội thoại lại, giữ ý chính nhưng giải phóng chỗ. Dùng khi bạn vẫn muốn tiếp tục mạch việc hiện tại.
• /clear - xóa sạch context, bắt đầu tươi. Dùng khi chuyển sang task khác không liên quan.
• Chia nhỏ task tuần tự. Thay vì "refactor cả module", giao từng file một. Đây là cách phòng bệnh tốt hơn chữa bệnh.
• Tránh dán nguyên file quá to vào chat - hãy để Claude Code tự đọc file khi cần thay vì nhồi hết vào context.
• Nếu treo cứng hẳn: thoát phiên (Ctrl+C) rồi mở lại. Mất context hiện tại nhưng dứt điểm được tình trạng đơ.

Muốn hiểu sâu hơn về cách quản lý context để hạn chế treo, cách làm việc bài bản dành cho người mới trong bài 10 bước bắt đầu Claude Code cho người mới sẽ giúp bạn giao việc gọn gàng từ đầu.

Lỗi 5 - Bị chặn quyền / permission (không chạy được lệnh)

Triệu chứng. Claude Code hỏi xác nhận liên tục trước mỗi lệnh, hoặc thẳng thừng từ chối chạy một lệnh / sửa một file, khiến công việc gián đoạn.

Nguyên nhân. Đây thường không phải "lỗi" mà là tính năng an toàn: permission mode đang chặn thao tác có rủi ro cho tới khi bạn cấp quyền. Mặc định Claude Code thận trọng với các lệnh có thể sửa/xóa file hoặc chạy shell.

Cách fix. Cấp quyền có kiểm soát:

• Khi Claude Code hỏi, chọn cho phép theo phiên cho những thao tác bạn tin tưởng, thay vì phải bấm đồng ý từng lần.
• Thêm các lệnh dùng thường xuyên vào allowlist để bớt bị hỏi lại.
• Hiểu các permission mode khác nhau để chọn mức phù hợp với việc đang làm.

Cảnh báo trung thực: đừng bật chế độ bỏ qua toàn bộ xác nhận một cách bừa bãi để "cho nhanh". Nó cho phép Claude Code chạy mọi lệnh không hỏi - tiện, nhưng rủi ro thật nếu model làm điều bạn không lường trước trên máy hoặc repo quan trọng. Chỉ dùng trong môi trường cô lập (sandbox/container).

Cấu hình quyền an toàn có nhiều lớp, mình sẽ tách thành một bài deep-dive riêng về quyền & permission mode Claude Code để bạn set một lần dùng lâu.

Vẫn lỗi lặt vặt? Checklist & khi nào cần cài lại

Nếu đã qua 5 nhóm trên mà vẫn dính lỗi vặt, chạy hết checklist này trước khi nghĩ tới cài lại:

• Cập nhật bản mới nhất: npm i -g @anthropic-ai/claude-code - nhiều bug đã được vá ở bản sau.
• Kiểm tra Node đang ở bản LTS (một số lỗi khó hiểu đến từ Node quá cũ hoặc quá mới).
• Chỉ mở một terminal chạy Claude Code cho mỗi project để tránh xung đột và process mồ côi.
• Xóa cache credential bằng claude logout rồi đăng nhập lại.
• Cài lại sạch: gỡ hẳn rồi cài lại theo hướng dẫn cài đặt Claude Code.
• Chưa rõ công cụ hoạt động thế nào? Đọc lại Claude Code là gì để nắm mô hình đúng - nhiều "lỗi" thực ra là hiểu nhầm cách nó vận hành.

Khi nào cần liên hệ support Anthropic: lỗi kéo dài dù máy bạn sạch, thông báo overloaded liên tục nhiều giờ, hoặc vấn đề về billing/tài khoản mà bạn không tự chỉnh được.

Đỡ lỗi & mạnh hơn nhờ bộ kit dựng sẵn (AgentKit)

Một phần lớn lỗi vặt đến từ môi trường mỗi máy mỗi khác: PATH lệch, config rời rạc, thiếu skill/statusline chuẩn. Nếu bạn muốn bớt loay hoay cấu hình thủ công, bộ kit AgentKit cho Claude Code cung cấp cấu hình, skill và cả statusline builder dựng sẵn giúp chuẩn hóa môi trường làm việc - đỡ được nhiều lỗi cấu hình lặt vặt và giúp phiên chạy ổn định hơn. Nó không "sửa" các lỗi CLI ở trên thay bạn, nhưng giảm bớt cơ hội để những lỗi đó phát sinh. Nếu muốn thử, bạn có thể dùng thử AgentKit (giảm 20% qua link) để xem bộ cấu hình sẵn có hợp với cách bạn làm không.

Câu hỏi thường gặp (FAQ)

Vì sao gõ claude lại báo command not found?

Vì thư mục chứa lệnh (npm global bin) chưa nằm trong biến môi trường PATH, nên shell không tìm thấy file. Chạy npm config get prefix, thêm thư mục /bin tương ứng vào PATH rồi mở lại terminal.

Claude Code chạy được trên Windows / PowerShell không?

Chạy được, nhưng trải nghiệm mượt hơn nhiều khi dùng WSL2 thay cho PowerShell/CMD native. WSL2 giúp tránh phần lớn lỗi PATH và quyền đặc thù của Windows.

"Rate limit reached" bao lâu thì hết?

Tùy nguồn. Nếu là quota gói Pro/Max, bạn phải chờ cửa sổ thời gian reset. Nếu là giới hạn RPM/TPM của API key, giảm số request đồng thời là hết ngay. Chạy /status để biết đang dính loại nào.

Claude Code bị treo phải làm sao?

Thường do context đầy. Dùng /compact để nén hội thoại hoặc /clear để reset, chia nhỏ task, tránh dán file quá to. Treo cứng thì thoát phiên (Ctrl+C) và mở lại.

Lỗi đăng nhập là do API key hay do gói?

Kiểm tra biến ANTHROPIC_API_KEY: nếu nó có giá trị, Claude Code có thể đi route API key thay vì gói bạn đã mua. Muốn dùng gói Pro/Max thì xóa biến đó rồi claude logout và claude login lại.

Cài lại Claude Code thế nào?

Gỡ gói cũ, chạy lại npm i -g @anthropic-ai/claude-code, đảm bảo Node đang ở bản LTS và thư mục npm global bin nằm trong PATH. Sau đó claude login lại từ đầu.

Kết luận + bước tiếp theo

Chốt lại: đừng sửa lung tung. Phân loại lỗi của bạn hay của Anthropic trước, rồi fix theo đúng nhóm triệu chứng - không chạy/PATH, auth, rate limit, treo/context, hay permission. Ba lệnh claude --version, /status và /compact giải quyết được phần lớn tình huống hằng ngày. Nếu bạn đang gặp lỗi ngay lúc cài, quay lại hướng dẫn cài đặt Claude Code; còn nếu mới bắt đầu và muốn tránh lỗi từ gốc, theo 10 bước cho người mới. Muốn chuẩn hóa môi trường để đỡ lỗi vặt lâu dài, tham khảo thêm review AgentKit cho Claude Code.