Khắc phục sự cố cài đặt và đăng nhập

Nếu cài đặt thất bại hay không đăng nhập được, tìm lỗi của bạn bên dưới. Với sự cố lúc chạy sau khi Claude Code đã hoạt động, xem Khắc phục sự cố. Với vấn đề cấu hình như settings không áp dụng hay hook không chạy, xem Debug cấu hình của bạn.

Tìm lỗi của bạn

Bạn thấy gì	Cách xử lý
command not found: claude hoặc 'claude' is not recognized	Sửa PATH
syntax error near unexpected token '<'	Install script trả về HTML
curl: (22) The requested URL returned error: 403	Install script trả về 403
curl: (23) hoặc curl: (56) Failure writing output to destination	Kiểm tra kết nối hoặc dùng installer khác
Killed khi cài trên Linux, hoặc exit code 137	Giải phóng bộ nhớ hoặc thêm swap
TLS connect error hoặc SSL/TLS secure channel	Cập nhật CA certificate
Failed to fetch version hoặc không kết nối được server tải về	Kiểm tra mạng và proxy
irm is not recognized hoặc && is not valid	Dùng đúng lệnh cho shell của bạn
Cask 'claude-code' is unavailable	Cập nhật Homebrew
'bash' is not recognized as the name of a cmdlet	Dùng lệnh cài đặt Windows
A parameter cannot be found that matches parameter name 'fsSL'	Dùng lệnh cài đặt Windows
Claude Code on Windows requires either Git for Windows (for bash) or PowerShell	Cài một shell
Claude Code does not support 32-bit Windows	Mở đúng PowerShell 64-bit
The process cannot access the file ...	Xoá thư mục downloads và thử lại
Error loading shared library	Sai biến thể binary
Illegal instruction	Lệch kiến trúc hoặc tập lệnh CPU
cannot execute binary file: Exec format error trong WSL	Lỗi WSL1 với binary mới
PowerShell installer xong nhưng không thấy claude hoặc thấy bản cũ	Thêm thư mục cài vào PATH, mở terminal mới
dyld: cannot load, dyld: Symbol not found, Abort trap trên macOS	Binary không tương thích
claude update hoặc claude doctor treo	Di chuyển thư mục ở đường dẫn shell config
running scripts is disabled on this system hoặc PSSecurityException	Cho phép npm shim chạy
Error: claude native binary not installed	Hoàn tất cài đặt npm
App unavailable in region	Claude Code chưa hỗ trợ ở quốc gia của bạn
unable to get local issuer certificate	Cấu hình CA certificate của công ty
OAuth error hoặc 403 Forbidden	Sửa xác thực
Could not load the default credentials / Could not load credentials from any providers	Credential Bedrock/Vertex/Foundry
ChainedTokenCredential authentication failed	Credential Bedrock/Vertex/Foundry
API Error: 500, 529 Overloaded, 429, lỗi 4xx/5xx khác	Xem Tra cứu lỗi

Nếu lỗi không nằm trong danh sách, làm theo các bước chẩn đoán dưới để tìm nguyên nhân.

Mẹo

Nếu không muốn dùng terminal, Claude Code Desktop app cho phép cài và dùng Claude Code qua giao diện đồ hoạ.

Chạy các bước chẩn đoán

Kiểm tra kết nối mạng

Installer tải từ downloads.claude.ai. Kiểm tra kết nối:

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

Trên PowerShell, chạy curl.exe -sI thay vì curl (PowerShell alias curl thành Invoke-WebRequest, không nhận cờ -sI).

• HTTP/2 200: kết nối tới server thành công
• 403: thường là proxy/network filter chặn host, hoặc Claude Code chưa hỗ trợ khu vực của bạn
• 5xx: thường là sự cố tạm thời của dịch vụ, đợi rồi thử lại
• Không có output, Could not resolve host, hay timeout: mạng đang chặn kết nối

Nếu sau proxy công ty, đặt HTTPS_PROXY và HTTP_PROXY trỏ tới proxy trước khi cài:

macOS/Linux

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

Windows PowerShell

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

Kiểm tra PATH

Nếu cài thành công nhưng chạy claude báo command not found, thư mục cài chưa nằm trong PATH. Installer đặt claude tại ~/.local/bin/claude (macOS/Linux) hoặc %USERPROFILE%\.local\bin\claude.exe (Windows).

Ghi chú

VS Code extension không đặt claude ở vị trí này - nó bó một bản CLI riêng bên trong extension cho panel chat của mình, không thêm vào PATH. Nếu chỉ cài extension, ~/.local/bin/claude sẽ không tồn tại. Chạy standalone install để dùng claude từ terminal.

macOS/Linux, Zsh:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell, thêm thư mục cài vào User PATH:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Xác nhận: claude --version.

Kiểm tra cài đặt trùng lặp

Nhiều bản cài Claude Code cùng lúc có thể gây lệch version hoặc hành vi lạ.

which -a claude
ls -la ~/.local/bin/claude
ls -la ~/.claude/local/
npm -g ls @anthropic-ai/claude-code 2>/dev/null

~/.local/bin/claude là bản cài native (khuyến nghị giữ lại). ~/.claude/local/ là bản npm local cũ. Nếu có nhiều bản, gỡ bớt:

npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local
brew uninstall --cask claude-code

Windows: winget uninstall Anthropic.ClaudeCode.

Kiểm tra quyền thư mục

Installer cần quyền ghi vào ~/.local/bin/ và ~/.claude/ trên macOS/Linux.

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

Nếu không ghi được:

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

Kiểm tra binary có chạy được không

ls -la "$(command -v claude)"
ldd "$(command -v claude)" | grep "not found"
claude --version

Các sự cố cài đặt thường gặp

Install script trả về HTML thay vì shell script

Khi chạy lệnh cài, có thể thấy:

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

Hoặc trên PowerShell, iex cố chạy HTML/CSS như PowerShell script (lỗi parse chứa thẻ HTML hoặc CSS). Đôi khi thay vào đó là một 403 không kèm body HTML. Tất cả nghĩa là URL cài đặt trả về trang HTML hoặc lỗi thay vì script cài đặt - thường do vấn đề mạng, định tuyến khu vực, hoặc gián đoạn dịch vụ tạm thời (hoặc do quốc gia của bạn chưa được hỗ trợ, nếu trang HTML nói “App unavailable in region”).

Cách xử lý:

Dùng cách cài khác:

macOS (Homebrew)

brew install --cask claude-code

Windows (WinGet)

winget install Anthropic.ClaudeCode

Hoặc đợi vài phút rồi thử lại lệnh gốc.

command not found: claude sau khi cài đặt

Nền tảng	Thông báo lỗi
macOS	zsh: command not found: claude
Linux	bash: claude: command not found
Windows CMD	'claude' is not recognized as an internal or external command
PowerShell	claude : The term 'claude' is not recognized as the name of a cmdlet

Nghĩa là thư mục cài chưa nằm trong PATH của shell. Xem Kiểm tra PATH.

curl: (56) Failure writing output to destination

Lệnh curl ... | bash tải script và pipe cho Bash chạy. Lỗi này (và curl: (23) liên quan) nghĩa là Bash không nhận đủ script - kết nối bị gián đoạn. Kiểm tra kết nối bằng lệnh curl ở trên, hoặc dùng cách cài khác (Homebrew/WinGet).

Homebrew cask không có hoặc lỗi thời

brew update
brew install --cask claude-code

Cask claude-code theo dõi kênh stable, thường chậm hơn bản mới nhất khoảng một tuần; dùng brew install --cask claude-code@latest nếu muốn bản mới nhất.

Lỗi kết nối TLS hoặc SSL

Lỗi như curl: (35) TLS connect error, unable to get local issuer certificate, hay lỗi SSL/TLS trên PowerShell.

Cách xử lý:

1. Cập nhật CA certificate hệ thống: sudo apt-get install ca-certificates (Ubuntu/Debian)
2. Windows, bật TLS 1.2 trước khi cài:

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   irm https://claude.ai/install.ps1 | iex

3. Nếu sau proxy TLS-inspecting, trỏ curl vào CA bundle của công ty:

   curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
   export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

4. Windows, nếu mạng chặn kiểm tra revocation certificate (CRYPT_E_NO_REVOCATION_CHECK, CRYPT_E_REVOCATION_OFFLINE), dùng PowerShell installer (irm https://claude.ai/install.ps1 | iex) hoặc winget install Anthropic.ClaudeCode - cả hai không fail khi revocation server không tới được.

Failed to fetch version from downloads.claude.ai

downloads.claude.ai có thể bị chặn trên mạng của bạn. Kiểm tra kết nối như phần Kiểm tra kết nối mạng, đặt HTTPS_PROXY nếu cần, hoặc dùng cách cài khác (Homebrew/WinGet).

Sai lệnh cài đặt trên Windows

Nếu thấy 'irm' is not recognized, The token '&&' is not valid, fsSL không hợp lệ, hay 'bash' is not recognized - bạn đã copy lệnh cài cho shell/hệ điều hành khác.

• irm not recognized: đang ở CMD, không phải PowerShell. Mở PowerShell và chạy irm https://claude.ai/install.ps1 | iex, hoặc dùng installer CMD: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
• && not valid: đang ở PowerShell nhưng chạy lệnh CMD. Dùng PowerShell installer.
• fsSL không hợp lệ: chạy installer macOS/Linux trong PowerShell, nơi curl là alias của Invoke-WebRequest. Dùng PowerShell installer.
• bash not recognized: chạy installer macOS/Linux trên Windows. Dùng PowerShell installer.

running scripts is disabled on this system

Cài hay chạy Claude Code qua npm trên Windows có thể fail vì execution policy của PowerShell chặn script .ps1 mà npm tạo ra.

Cách xử lý:

1. Cho phép script cục bộ cho user hiện tại: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
2. Hoặc gọi launcher .cmd thay vì .ps1: npm.cmd, claude.cmd
3. Dùng PowerShell installer thay vì npm - nó cài một binary chứ không phải script .ps1

The process cannot access the file khi cài trên Windows

Nghĩa là installer không ghi được vào %USERPROFILE%\.claude\downloads, thường vì một lần cài trước vẫn đang chạy hoặc antivirus đang scan file. Đóng các cửa sổ PowerShell khác đang chạy installer, đợi antivirus xong, rồi xoá thư mục downloads và cài lại:

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

Cài đặt bị Killed trên server Linux ít RAM

Thông báo Killed (exit code 137) thường nghĩa là OOM killer của Linux chấm dứt bước claude install vì hết bộ nhớ trống - hay gặp trên VPS/cloud instance nhỏ. Cài đặt cần khoảng 512MB RAM trống; chạy Claude Code cần nhiều hơn (tối thiểu 4GB RAM).

Cách xử lý:

1. Thêm swap:

   sudo fallocate -l 2G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile

2. Đóng bớt process khác trước khi cài
3. Dùng instance lớn hơn nếu có thể

Cài đặt treo trong Docker

Cài Claude Code trong Docker container với quyền root vào / có thể gây treo. Đặt WORKDIR trước khi chạy installer để giới hạn phạm vi scan:

WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash

Tăng giới hạn bộ nhớ Docker nếu dùng Docker Desktop: docker build --memory=4g .

claude update hoặc claude doctor treo

Hai lệnh này scan các file cấu hình shell (~/.zshrc, ~/.bashrc, ~/.config/fish/config.fish, v.v.) để tìm alias claude cũ. Nếu một trong các path đó là thư mục thay vì file, hai lệnh có thể treo trên các bản Claude Code cũ. Tìm thư mục gây lỗi:

ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

Di chuyển thư mục đó đi, hoặc cập nhật Claude Code lên bản mới nhất (cài lại bằng install script vì claude update cũng treo trên bản bị lỗi).

Claude Desktop ghi đè lệnh claude trên Windows

Bản Claude Desktop cũ có thể đăng ký Claude.exe trong WindowsApps được ưu tiên trên PATH hơn Claude Code CLI, khiến chạy claude mở app Desktop thay vì CLI. Cập nhật Claude Desktop lên bản mới nhất để sửa.

Claude Code trên Windows cần Git for Windows hoặc PowerShell

Git for Windows là tuỳ chọn - Claude Code dùng PowerShell tool khi không có Git Bash, nên lỗi này nghĩa là không tìm thấy shell nào.

Nếu thiếu PowerShell trong PATH, thêm C:\Windows\System32\WindowsPowerShell\v1.0\ vào PATH, hoặc cài PowerShell 7. Để cài Git for Windows, tải từ git-scm.com và chọn “Add to PATH” lúc cài.

Nếu Git đã cài nhưng Claude Code không tìm thấy, đặt path trong settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Claude Code không hỗ trợ Windows 32-bit

Windows có hai mục PowerShell trong Start menu: Windows PowerShell và Windows PowerShell (x86). Mục x86 chạy như process 32-bit và gây lỗi này kể cả trên máy 64-bit. Kiểm tra bằng [Environment]::Is64BitOperatingSystem - nếu True, mở lại Windows PowerShell không có hậu tố x86. Nếu False, máy đang chạy Windows 32-bit, không được Claude Code hỗ trợ.

Lỗi lệch musl hoặc glibc trên Linux

Lỗi thiếu shared library như libstdc++.so.6 sau khi cài nghĩa là installer tải sai biến thể binary.

ldd --version 2>&1 | head -1

GNU libc/GLIBC nghĩa là glibc; musl nghĩa là musl. Nếu đang trên glibc mà bị binary musl, gỡ và cài lại. Nếu thực sự đang trên musl (như Alpine), cài package cần thiết: apk add libgcc libstdc++ ripgrep.

Illegal instruction

Hai nguyên nhân riêng biệt: lệch kiến trúc (installer tải sai binary, ví dụ x86 trên ARM server - kiểm tra bằng uname -m), hoặc CPU thiếu tập lệnh AVX (thường gặp trên CPU đời trước 2013 hoặc VM không pass-through AVX). Kiểm tra trên VPS bằng grep -m1 -ow avx /proc/cpuinfo.

dyld: cannot load trên macOS

Binary không tương thích với phiên bản macOS hoặc phần cứng của bạn. Claude Code yêu cầu macOS 13.0 trở lên - cập nhật macOS để khắc phục.

Exec format error trên WSL1

Đây là một hồi quy (regression) đã biết với binary mới trên WSL1. Cách sạch nhất là chuyển distro sang WSL2:

wsl --set-version <DistroName> 2

Nếu phải ở lại WSL1, gọi binary qua dynamic linker bằng cách thêm hàm vào ~/.bashrc:

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

Lỗi npm install trong WSL

Chỉ áp dụng nếu bạn cài bằng npm install -g trong WSL (bỏ qua nếu dùng native installer).

• Lệch OS/platform: WSL có thể nhặt nhầm npm của Windows. Chạy npm config set os linux rồi npm install -g @anthropic-ai/claude-code --force (không dùng sudo).
• exec: node: not found: WSL đang dùng Node.js của Windows. Kiểm tra which npm/which node - path bắt đầu /mnt/c/ là binary Windows. Cài Node qua package manager của Linux hoặc nvm.
• Xung đột version nvm: nếu có nvm cả trong WSL lẫn Windows, thêm nvm loader vào ~/.bashrc:

  export NVM_DIR="$HOME/.nvm"
  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Lỗi quyền truy cập khi cài đặt

Nếu native installer báo lỗi permission, thư mục đích có thể không ghi được - xem Kiểm tra quyền thư mục. Nếu trước đó cài bằng npm và gặp lỗi permission riêng của npm, chuyển sang native installer: curl -fsSL https://claude.ai/install.sh | bash

Không tìm thấy native binary sau khi cài npm

Package npm @anthropic-ai/claude-code tải native binary như một optional dependency theo platform, rồi chạy postinstall script để đặt nó thành lệnh claude. Nếu bước tải hoặc postinstall bị bỏ qua, claude vẫn là placeholder script:

Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Kiểm tra:

• Optional dependency bị tắt: bỏ --omit=optional/--no-optional/--ignore-optional khỏi lệnh cài, kiểm tra .npmrc không đặt optional=false, rồi cài lại
• Install script bị tắt: chạy node node_modules/@anthropic-ai/claude-code/install.cjs thủ công, hoặc cài lại không dùng --ignore-scripts
• Platform không được hỗ trợ: binary dựng sẵn chỉ có cho darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64, win32-arm64
• npm mirror nội bộ thiếu package platform: đảm bảo mirror đồng bộ đủ tám package @anthropic-ai/claude-code-*

Đăng nhập và xác thực

Reset đăng nhập

Khi đăng nhập fail mà không rõ nguyên nhân, đăng nhập lại từ đầu thường giải quyết được hầu hết trường hợp:

1. /logout để đăng xuất hoàn toàn
2. Đóng Claude Code
3. Khởi động lại claude và đăng nhập lại

Nếu trình duyệt không tự mở khi login, nhấn c để copy URL OAuth vào clipboard rồi dán thủ công.

OAuth error: Invalid code

Mã login hết hạn hoặc bị cắt khi copy-paste. Nhấn Enter để thử lại và hoàn tất login nhanh sau khi trình duyệt mở. Nếu ở phiên remote/SSH, trình duyệt có thể mở sai máy - copy URL hiển thị trong terminal và mở trên trình duyệt local.

403 Forbidden sau khi đăng nhập

• Pro/Max: xác nhận subscription còn hiệu lực tại claude.ai/settings
• Console: xác nhận tài khoản có role “Claude Code” hoặc “Developer” (admin gán trong Console → Settings → Members)
• Sau proxy: proxy công ty có thể can thiệp request API

This organization has been disabled với subscription đang active

Biến môi trường ANTHROPIC_API_KEY cũ (từ công ty/dự án trước) đang override subscription của bạn. Bỏ đặt và dùng lại subscription:

unset ANTHROPIC_API_KEY
claude

Kiểm tra ~/.zshrc, ~/.bashrc, hay ~/.profile để xoá dòng export ANTHROPIC_API_KEY=.... Chạy /status để xác nhận phương thức xác thực đang active.

OAuth login fail trong WSL2, SSH, hoặc container

Trình duyệt thường mở trên host khác nên redirect không tới được callback server cục bộ của Claude Code. Sau khi đăng nhập, trình duyệt hiện một mã login - dán vào terminal ở prompt Paste code here if prompted.

Nếu trình duyệt không mở từ WSL2, đặt biến BROWSER trỏ tới trình duyệt Windows:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

Nếu paste mã vào prompt tương tác không có tác dụng, thử phím tắt paste khác của terminal, hoặc dùng claude auth login (đọc mã đã paste từ standard input).

Not logged in hoặc token hết hạn

Chạy /login để xác thực lại. Nếu xảy ra thường xuyên, kiểm tra đồng hồ hệ thống có chính xác không (token validation phụ thuộc timestamp). Trên macOS, login cũng có thể fail khi Keychain bị khoá - chạy claude doctor để kiểm tra, hoặc security unlock-keychain ~/Library/Keychains/login.keychain-db.

Credential Bedrock, Vertex, hoặc Foundry không nạp được

Nếu cấu hình dùng cloud provider và thấy Could not load credentials from any providers (Bedrock), Could not load the default credentials (Google Cloud’s Agent Platform), hay ChainedTokenCredential authentication failed (Microsoft Foundry) - CLI của cloud provider có thể chưa được xác thực trong shell hiện tại.

Amazon Bedrock

aws sts get-caller-identity

Google Cloud's Agent Platform

gcloud auth application-default login

Microsoft Foundry

az login

Nếu credential hoạt động trong terminal nhưng không trong VS Code/JetBrains extension, IDE process có thể chưa kế thừa shell environment - đặt biến trong settings của IDE hoặc mở IDE từ terminal đã export sẵn.

Vẫn chưa xử lý được

1. Kiểm tra GitHub repository để tìm issue đã biết, hoặc mở issue mới kèm hệ điều hành, lệnh cài đã chạy, và toàn bộ output lỗi
2. Nếu claude --version chạy được nhưng có vấn đề khác, chạy claude doctor
3. Nếu khởi động được phiên, dùng /feedback để báo lỗi
4. Nếu vấn đề liên quan tài khoản thay vì cài đặt (login loop, subscription không nhận, tổ chức bị disable), liên hệ hỗ trợ Anthropic qua claude.ai

Nguồn

Dịch và biên soạn từ Troubleshoot installation and login.