Troubleshooting và debugging

Chương này là tài liệu tra cứu nhanh khi Claude Code gặp sự cố: định tuyến triệu chứng đến đúng cách xử lý, debug config, lỗi cài đặt/login, error message runtime, và các env var hữu ích khi debug. Tất cả dựa trên docs chính thức.

Bắt đầu từ đâu

Không chắc lỗi thuộc nhóm nào? Chạy công cụ chẩn đoán trước:

• /doctor — chạy trong session: kiểm tra installation, settings, extensions, context usage; đề xuất fix và tự apply sau khi bạn xác nhận.
• claude doctor — chạy từ shell khi claude không khởi động được: in diagnostics read-only, không mở session.
• /mcp — kiểm tra trạng thái MCP server.

Định tuyến theo triệu chứng:

Triệu chứng	Đi tới
command not found, install fail, PATH, EACCES, TLS error	Lỗi cài đặt & login
Settings không apply, hook không fire, MCP không load	Debug config
API Error: 5xx, 529 Overloaded, 429, validation error	Error reference runtime
Login loop, OAuth error, 403 Forbidden, org disabled	Lỗi cài đặt & login
model not found / you may not have access to it	Request errors
High CPU/memory, chậm, treo, search thiếu file	Performance & stability
VS Code / JetBrains không detect Claude	Trang integration tương ứng

Debug config

Nguyên nhân phổ biến nhất: file config không load, load từ vị trí khác kỳ vọng, hoặc bị file khác override.

Xem những gì đã load vào context

Chạy /context đầu tiên để xác nhận CLAUDE.md, rules, skill... có thực sự nằm trong context window không. Sau đó dùng lệnh chuyên biệt cho từng loại:

Lệnh	Hiển thị
/context	Toàn bộ nội dung chiếm context window, chia theo category
/memory	Vị trí file memory theo user/project scope, mở editor
/skills	Skills khả dụng từ project, user, plugin
/hooks	Hook đang active, nhóm theo event
/mcp	MCP server đã kết nối và trạng thái
/permissions	Allow/deny rules đang có hiệu lực
/doctor	Setup checkup + đề xuất fix
/debug [issue]	Bật debug logging cho session và nhờ Claude chẩn đoán
/status	Nguồn settings đang active, có managed settings hay không

Lưu ý: CLAUDE.md ở subdirectory chỉ load on demand khi Claude đọc file trong thư mục đó bằng Read tool, không phải lúc khởi động session.

Kiểm tra settings precedence

Settings merge qua nhiều scope. managed luôn thắng khi có mặt. Còn lại, scope gần thắng scope rộng theo thứ tự: local → project → user. CLI flag và env var là lớp override thêm.

• settings.local.json override settings.json, cả hai override ~/.claude/settings.json.
• Khi một giá trị "có vẻ bị bỏ qua", thường là đang bị scope khác hoặc env var override.
• claude doctor (từ shell) in diagnostics read-only về install và settings.

Kiểm tra MCP server

Chạy /mcp để xem server, trạng thái kết nối, và bạn đã approve cho project chưa:

• Server scope project trong .mcp.json cần approve một lần. Nếu prompt bị bỏ qua, server vẫn disabled cho đến khi approve từ /mcp.
• Server hiện failed: thường do relative path trong command/args (resolve theo thư mục launch, không phải vị trí .mcp.json) — dùng absolute path.
• Server connected nhưng liệt kê 0 tool: chọn Reconnect từ /mcp. Nếu vẫn 0, chạy claude --debug mcp để xem stderr của server.

Kiểm tra hooks

Chạy /hooks để liệt kê hook đã đăng ký, nhóm theo event. Nếu hook không xuất hiện thì nó không được đọc: hook phải nằm dưới key "hooks" trong settings.json, không phải file riêng.

Nếu hook xuất hiện nhưng không fire, matcher thường là thủ phạm:

• matcher là một string dùng | để match nhiều tool: "Edit|Write". Từ v2.1.191, , cũng tương đương; bản cũ hơn thì , không match gì.
• Tên tool sai chính tả → matcher không match, fail âm thầm.
• matcher là array → schema error: cả file settings bị reject, /hooks không hiển thị hook nào từ file đó.
• Matching phân biệt hoa/thường: tên tool viết hoa (Bash, Edit, Write, Read), không phải "bash".

Sửa settings.json có hiệu lực trong session đang chạy sau một khoảng delay ổn định file — không cần restart. Để xem hook được đánh giá trực tiếp: claude --debug hooks rồi trigger tool call.

Test với clean configuration

Khi nghi customization là nguyên nhân:

# Tắt toàn bộ customization (CLAUDE.md, skills, plugins, hooks, MCP, custom command/agent)
claude --safe-mode

Trong safe mode, auth/model/built-in tool/permissions vẫn hoạt động bình thường; managed hooks và settings policy của tổ chức vẫn áp dụng. Nếu vấn đề biến mất → một trong các surface bị tắt là nguyên nhân.

Để bypass hoàn toàn ~/.claude, trỏ CLAUDE_CONFIG_DIR sang thư mục trống và launch từ nơi không có .claude/.mcp.json/CLAUDE.md:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Lần đầu sẽ hiện màn hình first-run setup (chọn theme...) — dấu hiệu clean dir đã có hiệu lực. Trên Linux/Windows sẽ phải login lại (credentials nằm dưới config dir); trên macOS credentials trong Keychain nên carry over. Managed settings vẫn áp dụng vì nằm ở system path ngoài ~/.claude.

Lỗi config thường gặp

Triệu chứng	Nguyên nhân	Fix
Hook không fire	matcher là array thay vì string	Dùng string với |: "Edit|Write"
Hook không fire	matcher viết thường "bash"	Match phân biệt hoa/thường: Bash, Edit...
Hook không fire	Hook để ở file riêng thay vì settings.json	Đặt dưới key "hooks" trong settings.json (chỉ plugin dùng hooks/hooks.json)
Permissions/hooks/env global bị bỏ qua	Thêm nhầm vào ~/.claude.json	permissions, hooks, env thuộc ~/.claude/settings.json (hai file khác nhau)
Giá trị settings.json bị bỏ qua	Cùng key set trong settings.local.json	settings.local.json override settings.json
Skill không xuất hiện trong /skills	File ở .claude/skills/name.md	Dùng folder: .claude/skills/name/SKILL.md
Skill có nhưng Claude không gọi	disable-model-invocation: true, hoặc description không khớp cách bạn hỏi	Xem badge "user-only" trong /skills
MCP trong .mcp.json không load	File nằm trong .claude/ hoặc dùng format Claude Desktop	Đặt .mcp.json ở repo root
MCP dưới mcpServers trong settings.json không hiện	settings.json không đọc key mcpServers	Định nghĩa trong .mcp.json hoặc claude mcp add --scope user
MCP fail từ một số thư mục	command/args dùng relative path	Dùng absolute path cho script local
MCP thiếu env var	Var đặt trong settings.json env (không propagate xuống MCP child)	Đặt env per-server trong .mcp.json
Bash(rm *) deny không chặn /bin/rm hay find -delete	Prefix rule match literal command string	Thêm pattern cho từng biến thể, hoặc dùng PreToolUse hook / sandbox

Error reference (runtime)

Match message trong terminal với section tương ứng. Các lỗi này áp dụng chung cho CLI, Desktop app, và Claude Code on the web.

Automatic retries

Claude Code retry các lỗi transient (server error, overloaded, timeout, throttle 429 tạm, dropped connection) tới 10 lần với exponential backoff trước khi hiện lỗi. Trong lúc retry, spinner hiện countdown Retrying in Ns · attempt x/y.

Không retry: TLS certificate validation failure (fail ngay lần đầu), server error sau khi đã stream output visible (giữ partial + gắn incomplete notice), Bedrock streaming content-type sai.

Tune bằng env var:

Variable	Default	Tác dụng
CLAUDE_CODE_MAX_RETRIES	10	Số lần retry (cap 15 từ v2.1.186). Giảm để lỗi lộ nhanh trong script
CLAUDE_CODE_RETRY_WATCHDOG	unset	Set 1 cho session không giám sát (CI): retry 429/529 vô hạn thay vì fail
API_TIMEOUT_MS	600000	Timeout mỗi request (ms). Tăng cho network/proxy chậm

Server errors

Lỗi từ inference provider, không phải account/request của bạn.

• API Error: 500 Internal server error — lỗi bất ngờ trong API. Check status.claude.com, đợi một phút rồi gõ try again.
• API Error: Repeated 529 Overloaded errors — API hết capacity toàn cục (không tính vào quota). Đợi vài phút, hoặc /model chuyển model khác (capacity tính theo model).
• Request timed out — API không phản hồi trước deadline (mặc định 10 phút). Retry, chia nhỏ task, hoặc tăng API_TIMEOUT_MS.
• The response above may be incomplete (Server error / Connection closed / Response stalled mid-response) — stream fail sau khi đã có output. Đọc phần đã stream (không mất gì), reply continue để Claude tiếp tục.

Usage limits

Quota gắn với account/plan (khác server error).

• You've hit your session limit / weekly limit / Opus limit — đợi tới reset time. Session/weekly dùng chung mọi model; riêng Opus limit thì /model chuyển model khác vẫn làm việc được. Chạy /usage xem hạn mức, /usage-credits mua thêm.
• Request rejected (429) — chạm rate limit của API key/Bedrock/Vertex project. Chạy /status xác nhận credential đúng (một ANTHROPIC_API_KEY lạc có thể route qua key tier thấp). Giảm concurrency: hạ CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY.
• Credit balance is too low — org Console hết prepaid credit. Nạp tại platform.claude.com/settings/billing, hoặc /login dùng subscription.

Authentication errors

Claude Code không xác thực được với API. Chạy /status bất cứ lúc nào để xem credential đang active.

• Not logged in · Please run /login — không có credential hợp lệ. Chạy /login; nếu kỳ vọng env var, xác nhận ANTHROPIC_API_KEY được set và export.
• Invalid API key · Fix external API key — key bị API reject. Chạy env | grep ANTHROPIC (direnv/dotenv/IDE terminal có thể load key cũ từ .env). Unset rồi /login.
• This organization has been disabled — ANTHROPIC_API_KEY cũ từ org bị disable đang override subscription. unset ANTHROPIC_API_KEY và xóa khỏi shell profile, relaunch.
• Login expired · Please run /login — Claude Code đã clear login sau khi refresh token fail. Chạy /login. Trong non-interactive mode, Failed to authenticate: OAuth session expired and could not be refreshed.
• OAuth token revoked / has expired — chạy /login; nếu lặp lại trong session, /logout rồi /login.

Env var và apiKeyHelper có precedence cao hơn /login, nên chạy /login không giúp khi chúng vẫn cung cấp key. Nếu login lặp lại giữa các lần launch: kiểm tra system clock chính xác; trên macOS kiểm tra Keychain (claude doctor).

Network and connection errors

Request không tới được đích, hoặc bị thứ gì đó giữa Claude Code và API sửa response.

• Unable to connect to API (ECONNREFUSED/ECONNRESET/ETIMEDOUT/fetch failed) — không có internet, VPN chặn api.anthropic.com, hoặc thiếu proxy. Test: curl -I https://api.anthropic.com (PowerShell: curl.exe -I). Sau proxy thì set HTTPS_PROXY. Qua gateway thì set ANTHROPIC_BASE_URL.
• SSL certificate verification failed / Self-signed certificate detected — proxy/appliance intercept TLS bằng cert riêng. Export CA bundle của tổ chức và trỏ NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem. Đừng set NODE_TLS_REJECT_UNAUTHORIZED=0 (tắt hết validation).
• 403 với x-deny-reason: host_not_allowed (cloud session) — network policy của môi trường chặn. Sửa allowlist trong cloud environment settings (Trusted → Custom), thêm domain.

Request errors

Lỗi ở prompt/request cụ thể:

• Prompt is too long / Error during compaction: Conversation too long / Request too large — context vượt giới hạn. Dùng /compact hoặc /clear, chia nhỏ.
• There's an issue with the selected model / Model ... is not a recognized model id — model ID sai hoặc không có quyền. Chạy /model chọn lại; kiểm tra ANTHROPIC_MODEL env.
• Claude Opus is not available with the Claude Pro plan — /model chuyển sang model khác.
• Model ... is restricted by your organization's settings — admin giới hạn; chọn model được phép.

Configuration warnings

• Ignoring N permissions.allow entries from ... this workspace has not been trusted — Claude Code đọc permissions.allow/additionalDirectories từ project settings nhưng chưa apply vì workspace chưa trusted. Chạy claude trong thư mục và accept trust dialog (deny/ask rule không bị ảnh hưởng).

Responses seem lower quality than usual

Không có error nhưng Claude kém hơn kỳ vọng — thường do conversation state:

• /model — xác nhận đúng model (một lựa chọn /model cũ hoặc ANTHROPIC_MODEL có thể đang ở model nhỏ hơn).
• /effort — kiểm tra reasoning level, tăng cho task khó.
• /context — nếu gần đầy, /compact ở breakpoint tự nhiên hoặc /clear.
• Rewind (Esc hai lần hoặc /rewind) về trước turn hỏng rồi rephrase — tốt hơn là sửa in-thread (giữ attempt sai trong context sẽ anchor các câu trả lời sau).

Lỗi cài đặt & login

command not found / PATH

Install xong nhưng claude báo not found: install dir chưa nằm trong PATH. Native installer đặt claude ở ~/.local/bin/claude (macOS/Linux) hoặc %USERPROFILE%\.local\bin\claude.exe (Windows).

# macOS/Linux: kiểm tra PATH
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

# Nếu không có output, thêm vào (Zsh):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

claude --version   # verify

Lưu ý: VS Code extension không đặt claude ở đây (nó bundle một bản CLI riêng). Cần chạy standalone install để dùng claude từ terminal.

Network / proxy khi install

Installer tải từ downloads.claude.ai. Test kết nối:

curl -sI https://downloads.claude.ai/claude-code-releases/latest   # PowerShell: curl.exe -sI

HTTP/2 200 = tới được server. Sau corporate proxy thì set trước khi install:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

Các lỗi khác:

• syntax error near unexpected token '<' / curl: (22) ... 403 — URL trả HTML/error thay vì script. Thử alternative installer (brew install --cask claude-code / winget install Anthropic.ClaudeCode), hoặc retry sau vài phút.
• TLS connect error / unable to get local issuer certificate — update CA certs; sau proxy TLS-inspecting thì curl --cacert /path/to/corporate-ca.pem ... và set NODE_EXTRA_CA_CERTS cho Claude Code.
• Killed / exit code 137 khi install trên Linux — OOM killer. Cần ~512MB free để install; thêm swap (fallocate -l 2G /swapfile ...) hoặc dùng instance lớn hơn.

Conflicting installations

Nhiều bản claude gây version mismatch:

which -a claude                              # liệt kê mọi binary trên PATH
ls -la ~/.local/bin/claude                   # native installer
ls -la ~/.claude/local/                      # legacy local npm install
npm -g ls @anthropic-ai/claude-code 2>/dev/null   # global npm install

Giữ lại native install (~/.local/bin/claude). Gỡ bản thừa: npm uninstall -g @anthropic-ai/claude-code, rm -rf ~/.claude/local, brew uninstall --cask claude-code, winget uninstall Anthropic.ClaudeCode.

Login & authentication

• Reset login: /logout → đóng Claude Code → claude → login lại. Nếu browser không tự mở, nhấn c để copy OAuth URL.
• 403 Forbidden sau login: Pro/Max — kiểm tra subscription active tại claude.ai/settings; Console — cần role "Claude Code" hoặc "Developer".
• This organization has been disabled dù có subscription — ANTHROPIC_API_KEY cũ override. unset ANTHROPIC_API_KEY; claude, xóa dòng export khỏi ~/.zshrc/~/.bashrc/~/.profile. Chạy /status xác nhận.
• OAuth login fail trong WSL2/SSH/container: browser mở trên host khác, redirect không về được callback. Paste login code vào prompt. Từ WSL2 có thể set BROWSER sang Chrome Windows path.
• Bedrock/Vertex/Foundry credentials không load (Could not load credentials from any providers...) — CLI cloud provider chưa auth trong shell hiện tại: aws sts get-caller-identity, gcloud auth application-default login, hoặc az login.

Performance & stability

High CPU hoặc memory

1. Dùng /compact thường xuyên để giảm context.
2. Đóng và restart Claude Code giữa các task lớn.
3. Thêm build directory lớn vào .gitignore.
4. Restart với claude --safe-mode để xem plugin/MCP/hook có phải nguồn gốc không.

Nếu memory vẫn cao, /heapdump ghi heap snapshot vào ~/Desktop. Không share file .heapsnapshot (chứa mọi string trong process); khi report chỉ đính kèm file -diagnostics.json.

Auto-compaction thrashing

Autocompact is thrashing: the context refilled to the limit... — compact thành công nhưng một file/tool output refill context ngay. Nhờ Claude đọc file oversized theo chunk nhỏ, /compact keep only the plan and the diff, chuyển việc file lớn sang subagent, hoặc /clear.

Command treo / freeze

1. Ctrl+C để hủy thao tác hiện tại.
2. Nếu vẫn không phản hồi, đóng terminal và restart — không mất conversation, chạy claude --resume trong cùng thư mục để tiếp tục.

Text bị lỗi trong integrated terminal (VS Code/Cursor)

Ký tự thành ô vuông/nhòe: GPU renderer của terminal. Chạy /terminal-setup để set terminal.integrated.gpuAcceleration thành "off" rồi reload window.

Search không tìm thấy file

Nếu Search tool, @file, custom agent/skill không tìm được file, ripgrep bundled có thể không chạy. Cài ripgrep hệ thống rồi:

# Cài (ví dụ macOS): brew install ripgrep
# Dùng bản hệ thống:
export USE_BUILTIN_RIPGREP=0
# Xác nhận: claude doctor -> dòng Search hiển thị path của rg hệ thống

Trên WSL, search qua filesystem Windows (/mnt/c/) trả ít kết quả hơn — chuyển project sang Linux filesystem (/home/), hoặc search cụ thể hơn theo thư mục/file type.

Biến môi trường hữu ích khi debug

Variable	Default	Dùng khi
CLAUDE_CONFIG_DIR	~/.claude	Trỏ sang dir trống để chạy clean config, bypass toàn bộ user config
CLAUDE_CODE_MAX_RETRIES	10	Giảm để lỗi lộ nhanh trong script; tăng cho outage dài
CLAUDE_CODE_RETRY_WATCHDOG	unset	Set 1 cho CI/unattended: retry 429/529 vô hạn
API_TIMEOUT_MS	600000	Tăng khi request timeout trên network/proxy chậm
NODE_EXTRA_CA_CERTS	unset	Trỏ tới CA bundle khi sau proxy TLS-inspecting
HTTPS_PROXY / HTTP_PROXY	unset	Route qua corporate proxy
ANTHROPIC_BASE_URL	unset	Trỏ tới LLM gateway/relay
USE_BUILTIN_RIPGREP	1	Set 0 để dùng rg hệ thống khi search lỗi
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY	10	Giảm để hạ concurrency khi bị 429
BASH_DEFAULT_TIMEOUT_MS	120000	Chỉnh timeout cho bash command dài
MCP_TIMEOUT	30000	Tăng timeout khởi động MCP server chậm
MAX_MCP_OUTPUT_TOKENS	—	Giới hạn output token của MCP tool

Ngoài ra, dùng flag debug trực tiếp: claude --debug (mọi thứ), claude --debug hooks, claude --debug mcp để xem log của từng subsystem.

Xem thêm

• content/en/docs/claude-code/troubleshooting.md — performance, hangs, search
• content/en/docs/claude-code/errors.md — error reference runtime đầy đủ
• content/en/docs/claude-code/debug-your-config.md — debug CLAUDE.md, settings, hooks, MCP, skills
• content/en/docs/claude-code/troubleshoot-install.md — lỗi install & login theo platform
• content/en/docs/claude-code/env-vars.md — danh sách env var đầy đủ
• Lệnh trong session: /doctor, /context, /status, /mcp, /hooks, /permissions, /debug, /feedback
• status.claude.com — trạng thái dịch vụ; GitHub issues