Tra cứu lỗi

Trang này liệt kê các lỗi runtime Claude Code hiển thị và cách khôi phục, cộng những gì cần kiểm tra khi phản hồi có vẻ không ổn mà không kèm lỗi cụ thể. Với lỗi cài đặt như command not found hay TLS lúc setup, xem Khắc phục sự cố cài đặt và đăng nhập.

Ghi chú

Claude Code gọi Claude API để lấy phản hồi model, nên hầu hết lỗi runtime ánh xạ tới một mã lỗi API bên dưới. Trang này nói về ý nghĩa từng lỗi bên trong Claude Code và cách khôi phục.

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

Thông báo	Mục
API Error: 500 Internal server error	Lỗi server
API Error: Repeated 529 Overloaded errors	Lỗi server
Request timed out	Lỗi server
Server error mid-response...	Lỗi server
Connection closed mid-response / Response stalled mid-stream	Lỗi server
Auto mode cannot determine the safety of...	Lỗi server
Agent terminated early due to an API error	Lỗi server
You've hit your session limit / weekly limit	Giới hạn sử dụng
Usage credits required for 1M context	Giới hạn sử dụng
Server is temporarily limiting requests	Giới hạn sử dụng
Request rejected (429)	Giới hạn sử dụng
Spend limit reached	Giới hạn sử dụng
Credit balance is too low	Giới hạn sử dụng
Could not update your spend limit	Giới hạn sử dụng
Not logged in · Please run /login	Xác thực
Could not resolve authentication method	Xác thực
Invalid API key	Xác thực
Your apiKeyHelper script is failing	Xác thực
Invalid auth token / Invalid ANTHROPIC_CUSTOM_HEADERS	Xác thực
This organization has been disabled	Xác thực
Your organization has disabled API key authentication	Xác thực
Your organization has disabled Claude subscription access	Xác thực
Routines are disabled by your organization's policy	Xác thực
Remote Control is only available when using Claude via api.anthropic.com	Xác thực
Remote Control disconnected...	Xác thực
OAuth token revoked / expired	Xác thực
API Error: 401 Invalid authentication credentials	Xác thực
Login expired · Please run /login	Xác thực
Anthropic profile login expired	Xác thực
OAuth token does not meet scope requirement	Xác thực
claude.ai rejected the session token	Xác thực
AWS credentials expired or invalid	Xác thực
AWS authentication failed	Xác thực
AWS default-chain credential resolve timed out	Xác thực
Unable to connect to API	Mạng
Unable to connect to Anthropic services	Mạng
Socket is closed	Mạng
Bedrock streaming response has an unexpected content-type	Mạng
SSL certificate verification failed	Mạng
403 kèm x-deny-reason: host_not_allowed trong phiên cloud	Mạng
Couldn't reconnect to your Remote Control session	Mạng
Couldn't share the transcript	Mạng
Prompt is too long	Lỗi request
Context exceeds the ...-token limit trong /context	Lỗi request
Error during compaction: Conversation too long	Lỗi request
Request too large	Lỗi request
Image was too large	Lỗi request
Unable to resize image	Lỗi request
PDF too large / PDF is password protected	Lỗi request
Extra inputs are not permitted	Lỗi request
There's an issue with the selected model	Lỗi request
Model ... is not a recognized model id	Lỗi request
Claude Opus is not available with the Claude Pro plan	Lỗi request
Model ... is restricted by your organization's settings	Lỗi request
thinking.type.enabled is not supported for this model	Lỗi request
max_tokens must be greater than thinking.budget_tokens	Lỗi request
API Error: 400 due to tool use concurrency issues	Lỗi request
<model> can't help with this	Lỗi request
<model>'s safeguards flagged this message	Lỗi request
Installation was killed... (exit code 137)	Lỗi cài đặt
The connection dropped while downloading the update	Lỗi cài đặt
--bg and --print conflict	Lỗi command-line
--json-schema is not a valid JSON Schema	Lỗi command-line
Error: Settings file exceeds the 2MiB limit	Lỗi command-line
Error: Workspace not trusted	Lỗi command-line
claude import is not yet available in this build	Lỗi command-line
Could not read Claude Code config	Lỗi command-line
Could not import <server>	Lỗi command-line
MCP tool ... not found	Lỗi command-line
Shell command failed for pattern... (/security-review)	Lỗi command-line
Input must be provided...	Lỗi command-line
Input contained only whitespace	Lỗi command-line
Diff is too large for ultrareview	Lỗi command-line
Could not find merge-base with...	Lỗi command-line
Your checkout has no branches	Lỗi command-line
Failed to resume the conversation	Lỗi command-line
No conversation found with session ID	Lỗi command-line
Marketplace "<name>" is registered from an untrusted source	Lỗi plugin
references ${user_config.*}	Lỗi plugin
Plugin archive integrity check failed	Lỗi plugin
would be spawned with zero tools	Lỗi tool
File is covered by a Read deny rule	Lỗi tool
Memory index is over its read limit	Lỗi tool
pkill: refusing to run	Lỗi tool
Failed to write to <teammate>'s inbox	Lỗi tool
Can't open MCP settings... (phiên nền)	Lỗi phiên chạy nền
blocked because the path...	Lỗi phiên chạy nền
This session has no saved transcript	Lỗi phiên chạy nền
This session was running agent '<name>'...	Lỗi phiên chạy nền
CLAUDE_CODE_PROCESS_WRAPPER: launcher...	Lỗi phiên chạy nền
EUNKNOWN: unknown error, uv_spawn	Lỗi phiên chạy nền
Claude Code process exited with code N	Lỗi wrapper/IDE
Could not locate the Claude CLI on PATH	Lỗi wrapper/IDE
Restored the code, but skipped N files	Cảnh báo rewind
Transcript writes are failing	Cảnh báo lưu phiên
Transcript saving is off - CLAUDE_CODE_SKIP_PROMPT_HISTORY...	Cảnh báo lưu phiên
Transcript saving is off - inherited CLAUDE_CODE_CHILD_SESSION...	Cảnh báo lưu phiên
Ignoring N permissions.allow entries...	Cảnh báo cấu hình
... is not matched by file permission checks	Cảnh báo cấu hình
the 200K limit isn't enforced	Cảnh báo cấu hình
[claude-code:unrecognized_model]	Cảnh báo cấu hình
Phản hồi có vẻ kém chất lượng hơn thường lệ	Chất lượng phản hồi

Tự động thử lại

Claude Code thử lại các lỗi tạm thời tối đa 10 lần với backoff tăng dần trước khi hiện lỗi cho bạn. Nó không phải lúc nào cũng thử lại một lỗi xảy ra giữa chừng phản hồi. Khi bạn thấy một lỗi trong trang này, Claude Code thường đã dùng hết số lần thử lại, trừ khi lỗi đó thuộc loại không thử lại.

Claude Code thử lại các lỗi:

• Lỗi server, phản hồi overloaded, và request timeout
• Kết nối bị ngắt giữa chừng, trước khi có phần nào của phản hồi hoàn tất
• 429 throttle tạm thời (kể cả throttle không kèm header quota của subscription plan, từ v2.1.199)
• Request bị từ chối vì input + max_tokens vượt context limit - Claude Code tự giảm max_tokens rồi thử lại, và chuyển sang compact thay vì tiếp tục thử khi không giảm được nữa
• Credential Google Cloud hết hạn trên Google Cloud’s Agent Platform - Claude Code xoá cache credential, thử lại tối đa 2 lần, chạy gcpAuthRefresh nếu bạn đã cấu hình

Claude Code không thử lại:

• Lỗi xác thực chứng chỉ TLS (proxy TLS-inspecting, thiếu NODE_EXTRA_CA_CERTS, chứng chỉ hết hạn) - báo lỗi ngay từ lần thử đầu để bạn sửa cấu hình chứng chỉ ngay
• Lỗi server, kết nối ngắt, hay stream đứng giữa chừng sau khi Claude đã hoàn thành một khối text hay tool call trong phản hồi đó - Claude Code giữ output đã hoàn thành và kết thúc lượt với thông báo phản hồi có thể chưa đầy đủ
• Amazon Bedrock trả response streaming với content-type bất thường (yêu cầu v2.1.208+) - thử lại sẽ gặp lại lỗi tương tự vì gateway/proxy đang biến đổi response

Tinh chỉnh hành vi thử lại

Biến	Mặc định	Hiệu ứng
CLAUDE_CODE_MAX_RETRIES	10	Số lần thử lại (tối đa 15). Đặt thấp hơn để lỗi hiện nhanh hơn trong script
CLAUDE_CODE_RETRY_WATCHDOG	unset	Đặt 1 trong phiên chạy tự động (như CI) để thử lại vô hạn lỗi 429/529; từ v2.1.199 còn nâng số lần thử lỗi tạm thời khác lên 300 (~3 giờ backoff) và bỏ trần 15 của CLAUDE_CODE_MAX_RETRIES nếu bạn tự đặt biến đó
API_TIMEOUT_MS	600000	Timeout mỗi request tính bằng mili-giây

Lỗi server

Hầu hết các lỗi này đến từ inference provider: dịch vụ của Anthropic trên Anthropic API, hoặc dịch vụ đằng sau endpoint của provider trên Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, hay một gateway tuỳ chỉnh.

API Error: 500 Internal server error

Lỗi bất ngờ bên trong API, không do prompt, settings, hay tài khoản của bạn.

Cách xử lý: kiểm tra status.claude.com hoặc trang trạng thái của provider; đợi một phút rồi gửi lại tin nhắn (gõ try again thay vì paste lại prompt dài); nếu lỗi kéo dài mà không có sự cố nào được đăng, chạy /feedback.

API Error: Repeated 529 Overloaded errors

API tạm thời hết công suất trên toàn hệ thống, không tính vào quota sử dụng của bạn. Kiểm tra status.claude.com, thử lại sau vài phút, hoặc chạy /model để chuyển sang model khác (công suất được theo dõi riêng theo từng model).

Request timed out

API không phản hồi trước deadline kết nối (mặc định 10 phút). Thử lại, chia nhỏ tác vụ dài, hoặc tăng API_TIMEOUT_MS nếu mạng/proxy chậm.

The response above may be incomplete

Một request streaming fail sau khi Claude đã bắt đầu tạo phản hồi. Gửi lại request có thể chạy trùng tool call, nên Claude Code giữ output đã hoàn thành và thêm thông báo này thay vì bỏ cả lượt. Biến thể gồm Server error mid-response, Connection closed mid-response, Your computer went to sleep mid-response, The response stopped arriving, Response stalled mid-stream.

Cách xử lý: trong phiên interactive, đọc phần phản hồi còn lại trên màn hình rồi gõ continue để Claude tiếp tục từ khối cuối đã hoàn thành. Ở non-interactive mode (-p), resume phiên và gửi continue.

Auto mode không xác định được độ an toàn của một hành động

Model phân loại của auto mode không tạo được quyết định, nên auto mode không tự duyệt hành động. Đọc, tìm kiếm, và sửa file trong thư mục làm việc bỏ qua bước phân loại này nên vẫn hoạt động bình thường trong mọi trường hợp dưới đây.

• Classifier tạm thời không khả dụng: thử lại sau vài giây, Claude thường tự thử lại
• Classifier trả về phản hồi không parse được: thử lại hành động, hoặc chạy claude --debug để xem log
• Một safety check khác chặn request classifier vì nội dung hội thoại trước đó (a safety check separate from auto mode blocked this request): đây không phải quyết định về hành động của bạn - thử lại sẽ không giúp ích; chuyển permission mode khác để tự duyệt, hoặc bắt đầu hội thoại mới
• Hội thoại vượt quá context window của classifier: chạy /compact để giảm kích thước hội thoại - Claude Code tự rơi về permission prompt thủ công cho hành động đó trong lúc chờ

Agent terminated early due to an API error

Một subagent fail request API vĩnh viễn (ví dụ chạm giới hạn sử dụng, hoặc hết lượt thử lại lỗi server) nên dừng trước khi hoàn thành tác vụ. Khớp phần chi tiết lỗi sau dấu hai chấm với mục tương ứng trong trang này (Giới hạn sử dụng hoặc Lỗi server) và làm theo các bước ở đó. Sau khi lỗi gốc hết, nhờ Claude thử lại tác vụ hoặc resume subagent.

Giới hạn sử dụng

Hầu hết lỗi ở mục này nghĩa là một quota gắn với tài khoản/plan của bạn đã dùng hết. Một vài lỗi hoạt động khác: Server is temporarily limiting requests là throttle phía server không liên quan quota plan, và Usage credits required for 1M context là kiểm tra entitlement chứ không phải quota đã cạn.

You’ve hit your session limit

Plan subscription có hạn mức sử dụng dạng rolling. Khi hết, Claude Code chặn request tới giờ reset ghi trong thông báo. Session/weekly limit dùng chung cho mọi model nên đổi model không khôi phục quyền truy cập; Opus limit chỉ áp dụng cho request Opus nên đổi sang model khác vẫn dùng được.

Cách xử lý: đợi tới giờ reset; với Opus limit, /model để đổi model khác; /usage để xem hạn mức và giờ reset; /usage-credits để mua thêm usage; nâng cấp plan tại claude.com/pricing nếu cần hạn mức cao hơn.

Usage credits required for 1M context

Model đã chọn dùng context window mở rộng 1M token, và plan của bạn chỉ bao gồm nó qua usage credits. Chạy /model để chọn variant không có hậu tố [1m], hoặc /usage-credits để bật billing theo mức dùng. Nếu lỗi vẫn còn sau /model, một model ID 1M có thể đang set ở nơi khác - xem thứ tự kiểm tra ở There’s an issue with the selected model. Để bỏ hẳn variant 1M khỏi model picker, đặt CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Server is temporarily limiting requests

Throttle ngắn hạn từ API, không liên quan quota plan của bạn. Được tự động thử lại kèm backoff. Đợi và thử lại, kiểm tra status.claude.com nếu kéo dài.

Request rejected (429)

Bạn đã chạm rate limit cấu hình cho API key, project Bedrock, hay project Google Cloud. Chạy /status để xác nhận credential active đúng như mong đợi - một ANTHROPIC_API_KEY sót lại có thể route request qua key tier thấp thay vì subscription của bạn; kiểm tra console provider để xem limit hiện tại; giảm concurrency (CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY, tránh chạy nhiều subagent song song, hoặc chuyển model nhỏ hơn cho script chạy khối lượng lớn).

Spend limit reached

spend limit reached (daily; resets ...) - cap chi tiêu do gateway/tổ chức đặt đã chạm. Đợi tới giờ reset ghi trong thông báo, hoặc làm theo hướng dẫn riêng của operator nếu có; nếu bạn chạm mức này thường xuyên, nhờ operator quản lý gateway nâng cap.

Credit balance is too low

Tổ chức Console của bạn đã hết credit trả trước. Nạp thêm credit tại platform.claude.com/settings/billing (cân nhắc bật auto-reload), hoặc chuyển sang xác thực subscription bằng /login nếu có plan Pro/Max/Team/Enterprise. Đặt spend cap theo từng workspace trong Console để tránh một dự án dùng hết credit chung.

Could not update your spend limit

Server từ chối thay đổi spend limit bạn thực hiện từ prompt xuất hiện khi chạm spend limit. Nếu thông báo kèm lý do, chọn giá trị khác thoả điều kiện đó; nếu không có lý do cụ thể, thử lại vì có thể là lỗi tạm thời; nếu vẫn fail, đổi limit từ billing settings của claude.ai trên trình duyệt thay vì trong CLI.

Lỗi xác thực

Các lỗi này nghĩa là Claude Code không chứng minh được danh tính của bạn với API. Chạy /status bất kỳ lúc nào để xem credential nào đang active.

Not logged in

Không có credential hợp lệ cho phiên này. Chạy /login để xác thực với subscription hay tài khoản Console. Nếu mong đợi một environment variable xác thực bạn, xác nhận ANTHROPIC_API_KEY đã set và export đúng shell. Với CI/automation, cấu hình script apiKeyHelper lấy key lúc khởi động.

Could not resolve authentication method

Phiên tới API client mà không có credential nào - thường gặp trong phiên chạy nền, cloud session, và bối cảnh Agent SDK. Nếu gặp trong phiên nền/cloud, nâng cấp lên v2.1.176 trở lên nếu credential thực ra đã cấu hình đúng. Xác nhận ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, hay credential cloud provider được đặt trong environment khởi động worker, không chỉ trong shell interactive. Với Agent SDK, xem thiết lập xác thực trong quickstart.

Invalid API key

ANTHROPIC_API_KEY hay script apiKeyHelper trả về key bị API từ chối. Kiểm tra lỗi gõ, xác nhận key chưa bị revoke trong Console; chạy env | grep ANTHROPIC để phát hiện key cũ nạp từ .env (tool như direnv hay plugin dotenv của IDE có thể tự nạp key cũ mà bạn không set thủ công); unset ANTHROPIC_API_KEY và /login để dùng subscription thay vào đó.

Your apiKeyHelper script is failing

Lệnh cấu hình trong setting apiKeyHelper thoát với lỗi, timeout, hay không in gì (hoặc in thứ gì đó khác ngoài key, như banner đăng nhập) ra stdout. Chạy lệnh trực tiếp trong shell để tái hiện lỗi, sửa để nó chỉ in key ra stdout (một token ASCII in được, tối đa 16.384 ký tự) và exit code 0. /login không giúp ích ở đây vì output của helper luôn được ưu tiên hơn login đã lưu khi setting còn tồn tại. /status hiện exit code và error output của helper mỗi lần nó fail.

Invalid request header

Biến thể: Invalid auth token (token từ ANTHROPIC_AUTH_TOKEN/CLAUDE_CODE_OAUTH_TOKEN), Invalid ANTHROPIC_CUSTOM_HEADERS (một cặp Name: Value bạn tự đặt sai định dạng), Invalid request header from the environment (một biến môi trường khác Claude Code copy vào header request, ví dụ CLAUDE_AGENT_SDK_CLIENT_APP). Đặt lại đúng biến/setting thông báo nêu tên; với ANTHROPIC_CUSTOM_HEADERS, giữ mỗi cặp Name: Value một dòng; chạy /status để xác nhận credential đang active.

This organization has been disabled

Một ANTHROPIC_API_KEY cũ từ tổ chức Console đã bị disable đang override login subscription của bạn. Unset biến này trong shell hiện tại và xoá khỏi shell profile, rồi khởi động lại claude. Nếu thông báo là Update or unset nghĩa là bạn chưa có login nào để fallback - unset key và /login, hoặc thay key bằng key từ tổ chức Console còn active.

Your organization has disabled API key authentication

Admin tổ chức Console đã tắt xác thực bằng API key. Nếu thông báo nêu ANTHROPIC_API_KEY, unset biến này (shell hiện tại + shell profile/.env) rồi khởi động lại claude; nếu nêu apiKeyHelper, xoá setting đó khỏi settings.json. Chạy /login để đăng nhập bằng tài khoản claude.ai.

Your organization has disabled Claude subscription access

Tổ chức đã tắt truy cập Claude Code qua subscription. Nhờ admin bật lại, hoặc xác thực bằng Console API key thay vì subscription.

Routines are disabled

Routines are disabled by your organization's policy - nhờ một Owner trong tổ chức bật toggle Routines tại claude.ai/admin-settings/claude-code. Với việc chạy theo lịch một lần không cần routine cấp tổ chức, xem scheduled tasks.

Remote Control requires Anthropic API

Remote Control is only available when using Claude via api.anthropic.com - thường do một biến CLAUDE_CODE_USE_* (như CLAUDE_CODE_USE_BEDROCK), hoặc ANTHROPIC_BASE_URL trỏ tới host khác api.anthropic.com (kể cả khi bạn đăng nhập bằng claude.ai - yêu cầu v2.1.196+ để chặn trường hợp này). Unset biến thông báo nêu tên và khởi động lại phiên, hoặc bật Remote Control từ một phiên nói thẳng với Anthropic API.

Remote Control could not refresh login

Login claude.ai đã lưu bị từ chối hoặc hết hạn, hoặc không tìm thấy OAuth token để refresh. Chạy /login để đăng nhập lại; với thông báo yêu cầu thêm bước, chạy /remote-control sau đó để kết nối lại (một số biến thể tự kết nối lại sau khi bạn login xong).

OAuth token revoked or expired

Login đã lưu không còn hợp lệ - bị revoke (đăng xuất mọi nơi hoặc admin gỡ quyền) hoặc hết hạn (refresh tự động fail giữa phiên). Chạy /login để đăng nhập lại; nếu lỗi lặp lại trong cùng phiên, /logout trước rồi /login. Nếu xác thực bằng biến CLAUDE_CODE_OAUTH_TOKEN, tạo token mới bằng claude setup-token thay vì trông đợi /login tự thay giá trị biến.

API Error: 401 Invalid authentication credentials

API nhận diện đúng định dạng credential nhưng từ chối tài khoản/tổ chức đứng sau. Chạy /status để xem credential nào đang active và xử lý theo đó: rotate API key nếu đó là nguồn active (/login không ghi đè được API key), hoặc /login lại nếu chỉ có login. Nếu ANTHROPIC_BASE_URL trỏ tới LLM gateway, phần text sau 401 là message của gateway chứ không phải của Anthropic - sửa credential gateway yêu cầu thay vì login lại.

Login expired

Claude Code cố gia hạn login đã lưu và dịch vụ OAuth từ chối refresh token đã lưu, nên Claude Code xoá credential đã lưu. Chạy /login để đăng nhập lại. Trong non-interactive mode và Agent SDK, thông báo là Failed to authenticate: OAuth session expired and could not be refreshed - với automation không đăng nhập tương tác được, dùng ANTHROPIC_API_KEY hoặc claude setup-token.

Anthropic profile login expired

Anthropic profile login expired · Re-authenticate your Anthropic profile - profile do ANTHROPIC_PROFILE chỉ định hoặc tự phát hiện từ thư mục cấu hình đã hết hạn. Đăng nhập lại profile đó bằng tool đã tạo nó; nếu admin cấp credential, nhờ họ cấp bản mới. Chạy /status để xác nhận credential/profile đang active; unset ANTHROPIC_PROFILE nếu muốn chuyển sang cách xác thực khác.

OAuth scope requirement

OAuth token does not meet scope requirement: user:profile - token hiện tại thiếu scope cần. Chạy /login để lấy token mới với scope hiện hành (không cần logout trước).

claude.ai rejected the session token

claude.ai rejected the session token. Run /login, then reconnect. - chạy /login để đăng nhập lại, rồi reconnect connector bằng /mcp hoặc /mcp reconnect <server>. Reconnect trước khi login lại sẽ giữ nguyên trạng thái lỗi.

AWS credentials expired or invalid

Chạy lệnh awsAuthRefresh được nêu trong thông báo (ví dụ aws sso login --profile myprofile) ở terminal khác và hoàn tất đăng nhập trình duyệt, rồi thử lại - hoặc trong phiên interactive, /login → chọn 3rd-party platform → Claude Platform on AWS · refresh credentials để chạy lệnh đó không cần khởi động lại Claude Code. Nếu lỗi vẫn còn sau khi refresh, xác nhận identity hợp lệ bằng aws sts get-caller-identity.

AWS authentication failed

Tương tự lỗi credential ở trên nhưng là lỗi 403 - nếu credential vẫn current, kiểm tra IAM permission và quyền truy cập model đã bật cho account/region đang dùng. Chạy aws sts get-caller-identity để xác nhận đúng identity request đang dùng - AWS_PROFILE hay profile mặc định bị lệch là nguyên nhân thường gặp.

AWS default-chain credential resolve timed out

Chạy aws sts get-caller-identity với cùng AWS_PROFILE - nếu cũng treo, sửa profile (một lệnh credential_process yêu cầu tương tác là nguyên nhân thường gặp). Hoàn tất bước đăng nhập (ví dụ aws sso login --profile myprofile) trước khi chạy Claude Code. Nếu chain của bạn cần hơn 60 giây hợp lệ (SSO+MFA qua wrapper như aws-vault), tăng giới hạn bằng CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

Lỗi mạng và kết nối

Các lỗi này nghĩa là một request mạng từ Claude Code không tới được đích, hoặc thứ gì đó giữa Claude Code và API đã làm thay đổi phản hồi trên đường về. Chúng thường bắt nguồn từ mạng cục bộ, proxy, hay firewall của bạn.

Unable to connect to API

Kết nối TCP tới API fail hoặc không bao giờ hoàn tất. Nguyên nhân phổ biến: không có internet, VPN chặn api.anthropic.com, hay thiếu cấu hình proxy công ty bắt buộc. Kiểm tra bằng curl -I https://api.anthropic.com (Windows PowerShell: curl.exe -I ...), đặt HTTPS_PROXY nếu sau proxy, hoặc ANTHROPIC_BASE_URL nếu dùng LLM gateway. Trên Linux/WSL, kiểm tra /etc/resolv.conf; trên macOS, VPN client đã tắt/gỡ có thể để lại tunnel interface (ifconfig tìm utun thừa); Docker Desktop và runtime container tương tự có thể chặn traffic đi ra - thử tắt để loại trừ.

Unable to connect to Anthropic services

Biến thể của lỗi trên xuất hiện lúc setup/login. Nếu thông báo nêu tên biến proxy, kiểm tra giá trị đúng chưa và nhờ team mạng allowlist host đó. Làm theo các bước kiểm tra ở Unable to connect to API. Nếu mạng mở mà lỗi vẫn còn, Claude Code có thể chưa khả dụng ở quốc gia của bạn.

Socket is closed

Kết nối mang phản hồi streaming bị đóng khi phản hồi còn đang tới, thường do proxy công ty trên Windows ngắt tunnel giữa chừng. Cập nhật Claude Code lên bản v2.1.214 trở lên (claude update) và gửi lại tin nhắn; nếu vẫn lặp lại sau nhiều lượt sau proxy, kiểm tra lại cấu hình proxy.

Bedrock streaming content-type

Response streaming từ Amazon Bedrock có content-type khác định dạng nhị phân gốc - thường do gateway/proxy giữa Claude Code và Bedrock đang biến đổi response. Cấu hình gateway pass-through nguyên trạng body và header Content-Type; nếu chỉ header bị đổi còn body binary vẫn nguyên, đặt CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 tạm thời trong lúc chờ sửa gateway.

Lỗi SSL certificate

Một proxy hay thiết bị bảo mật trên mạng của bạn đang can thiệp lưu lượng TLS bằng chứng chỉ riêng mà Claude Code không tin cậy. Export CA bundle của tổ chức và trỏ Claude Code vào đó bằng NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem. Không đặt NODE_TLS_REJECT_UNAUTHORIZED=0, vì nó tắt hoàn toàn việc xác thực chứng chỉ.

Host not allowed trong phiên cloud

Một request HTTP đi ra từ phiên cloud hay routine bị chặn bởi network policy của môi trường - không phải sự cố mạng phía client. Mở routine hoặc cloud session, đổi Network access từ Trusted sang Custom và thêm domain bị chặn vào Allowed domains.

Couldn’t reconnect Remote Control

Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume. - chạy /remote-control để thử kết nối lại, hoặc claude --remote-control để tạo phiên Remote Control mới.

Couldn’t share the transcript

Chạy /feedback để gửi transcript kèm mô tả sự cố. Nếu request khác cũng đang fail, kiểm tra kết nối mạng theo Unable to connect to API.

Lỗi request

Các lỗi này liên quan tới nội dung request của bạn.

Prompt is too long

Hội thoại cộng file đính kèm vượt quá context window của model. Chạy /compact để tóm tắt lượt trước và giải phóng không gian, hoặc /clear để bắt đầu lại. Chạy /context để xem chi tiết những gì đang chiếm context window; disable MCP server không dùng bằng /mcp disable <name>; cắt gọn CLAUDE.md. Subagent kế thừa toàn bộ định nghĩa MCP tool của phiên cha nên có thể đầy context ngay từ lượt đầu - tắt MCP server không cần trước khi tạo subagent.

Context exceeds the token limit

/context hiện cảnh báo này ở đầu output khi hội thoại đã lớn hơn context window của model. Chạy /compact hoặc /clear như gợi ý trong thông báo.

Error during compaction: Conversation too long

/compact chính nó fail vì không đủ context trống để chứa bản tóm tắt. Nhấn Esc hai lần để lùi lại vài tin nhắn rồi thử /compact lại; nếu vẫn không đủ, /clear để bắt đầu phiên mới (hội thoại cũ vẫn còn, mở lại bằng /resume).

Request too large

Kích thước request thô vượt giới hạn 32MB của API. Nếu message nêu ảnh/tài liệu là nguyên nhân, Claude Code tự thử lại sau khi loại bỏ chúng; nếu message nêu chỉ riêng phần text tin nhắn đã vượt giới hạn (không nén được), nhấn Esc hai lần để lùi qua lượt đã thêm nội dung lớn, hoặc /clear để bắt đầu lại. Tham chiếu file lớn bằng đường dẫn thay vì paste nội dung.

Image was too large

Hình ảnh paste hoặc đính kèm vượt giới hạn kích thước/kích cỡ của API. Resize ảnh trước khi paste - API chấp nhận ảnh tới 8000px cạnh dài nhất cho một ảnh đơn, hoặc 2000px khi có nhiều ảnh trong context. Chụp vùng cụ thể thay vì cả màn hình.

Unable to resize image

Claude Code không tự resize được ảnh. Nếu thông báo yêu cầu đổi định dạng, chuyển ảnh sang PNG/JPEG/GIF/WebP rồi đính kèm lại; nếu thông báo nêu giới hạn kích thước/pixel cụ thể, tự resize/nén ảnh xuống dưới ngưỡng đó trước khi đính kèm.

Lỗi PDF

PDF đính kèm không xử lý được: quá lớn (giới hạn 100 trang, 20MB), có mật khẩu, hay file không hợp lệ. Nhờ Claude đọc theo range trang bằng Read tool, hoặc trích xuất text bằng pdftotext trước; với PDF có mật khẩu/hỏng, gỡ mật khẩu hoặc export lại từ ứng dụng gốc.

Extra inputs are not permitted

API Error: 400 ... context_management hoặc lỗi về header anthropic-beta - thường xảy ra khi request đi qua một gateway không forward đúng các header/tính năng thử nghiệm. Cấu hình gateway forward header anthropic-beta nguyên trạng; nếu không sửa được gateway, đặt CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 để tắt các capability thử nghiệm tạm thời.

There’s an issue với model đã chọn

Model cấu hình không tồn tại hoặc bạn không có quyền dùng nó. Trong CLI interactive, chạy /model để chọn model khả dụng cho tài khoản; ở non-interactive, truyền --model hợp lệ. Ưu tiên dùng alias (sonnet, opus) thay vì ID đầy đủ có version để tránh lỗi thời. Nếu model sai cứ quay lại, kiểm tra theo thứ tự ưu tiên: cờ --model → biến ANTHROPIC_MODEL → field model trong .claude/settings.local.json → .claude/settings.json → ~/.claude/settings.json, xoá giá trị cũ ở đó.

Model is not a recognized model id

Chuỗi model bạn truyền không phải alias, ID mà bản Claude Code này biết, hay ID bắt đầu bằng claude-. Nguyên nhân thường là gõ sai, dùng display name (Sonnet 5) thay vì ID (claude-sonnet-5), hay alias chỉ bản mới hơn mới nhận diện được. Chạy /model không kèm tham số để mở picker. Kiểm tra này chỉ chạy trên Anthropic API - provider khác (kể cả ANTHROPIC_BASE_URL tuỳ chỉnh) tự định nghĩa tên model nên Claude Code chấp nhận mọi chuỗi.

Claude Opus is not available with the Claude Pro plan

Plan subscription hiện tại không bao gồm model đã chọn. Chạy /model chọn model khác, hoặc nếu vừa nâng cấp plan, /logout rồi /login lại vì token lưu phản ánh plan lúc đăng nhập.

Model is restricted by your organization’s settings

Admin tổ chức đã tắt model này, hoặc nó bị loại khỏi allowlist availableModels trong managed settings. Chạy /model để chọn từ các model tổ chức cho phép (model bị hạn chế sẽ ẩn khỏi picker); nếu model bị hạn chế đang set trong --model/ANTHROPIC_MODEL/settings/frontmatter subagent, sửa lại giá trị đó để cảnh báo không lặp lại.

thinking.type.enabled is not supported

Version Claude Code hoặc Agent SDK quá cũ so với model đang dùng (mỗi model yêu cầu một version tối thiểu khác nhau). Chạy claude update và khởi động lại; nếu không nâng cấp được, /model chuyển về Opus 4.6 hoặc Sonnet 4.6; với Agent SDK, nâng cấp package SDK.

Thinking budget exceeds output limit

max_tokens must be greater than thinking.budget_tokens - hạ MAX_THINKING_TOKENS, hoặc nâng CLAUDE_CODE_MAX_OUTPUT_TOKENS lên trên mức thinking budget.

Tool use hoặc thinking block mismatch

API Error: 400 due to tool use concurrency issues, unexpected tool_use_id..., hay thinking blocks ... cannot be modified - hội thoại vào trạng thái không nhất quán, thường do bug đã fix ở bản Opus 4.7/4.8 cũ hơn v2.1.156. Chạy claude update trước nếu đang dùng Opus 4.7/4.8; sau đó /rewind hoặc nhấn Esc hai lần để lùi về checkpoint trước lượt bị lỗi rồi tiếp tục.

Usage policy refusal

Claude từ chối hỗ trợ yêu cầu dựa trên usage policy. Nhấn Esc hai lần hoặc /rewind để lùi về checkpoint trước lượt gây từ chối rồi diễn đạt lại; nếu không xác định được lượt nào, /clear để bắt đầu hội thoại mới trong cùng dự án (hội thoại cũ vẫn còn trong /resume). Ở non-interactive mode, thử lại với prompt diễn đạt khác trong phiên mới, hoặc đổi --model.

Safety measures flagged a cybersecurity topic

Cơ chế an toàn của Claude phát hiện chủ đề liên quan bảo mật mạng và từ chối phản hồi - có thể xảy ra khi thảo luận offensive security, khai thác lỗ hổng, hay chủ đề nhạy cảm khác kể cả trong ngữ cảnh phòng thủ/giáo dục. Diễn đạt lại tập trung vào biện pháp phòng thủ, thực hành bảo mật tốt, hay kịch bản kiểm thử được uỷ quyền; cung cấp thêm ngữ cảnh về mục đích nghiên cứu/phòng thủ hợp pháp. Nếu công việc cần nội dung này thường xuyên, đăng ký Cyber Verification Program; nếu bị gắn cờ nhầm, chạy /feedback.

Lỗi cài đặt

Installation was killed before it could finish

Tiến trình cài đặt nhận SIGKILL (exit code 137), thường do hết bộ nhớ. Giải phóng RAM/disk, chạy lại claude update. Xem thêm Cài đặt bị Killed trên server Linux ít RAM.

The connection dropped while downloading the update

Kết nối mạng bị ngắt khi tải bản cập nhật (gồm cả Download timed out: exceeded the total deadline). Kiểm tra kết nối internet, chạy claude update lại; nếu timeout thường xuyên, tăng API_TIMEOUT_MS; nếu proxy công ty cắt transfer, nhờ team mạng allowlist downloads.claude.ai.

Lỗi command-line

Lỗi command-line

Các lỗi validate tham số CLI như --bg and --print conflict - --bg nhận prompt làm positional argument, nên bỏ -p/--print và chạy claude --bg "<task>" thẳng.

The —json-schema value is not a valid JSON Schema

Sửa phần schema thông báo lỗi nêu tên rồi chạy lại lệnh; nếu lỗi là “schema too large”, giảm độ lồng nhau và tái sử dụng $ref.

Settings file exceeds the 2MiB limit

File .claude/settings.json hay settings.local.json quá lớn. Bỏ setting không cần thiết hay nội dung inline lớn; chuyển tool definition/chỉ dẫn lớn ra file riêng và tham chiếu theo đường dẫn.

Workspace not trusted khi khởi động Remote Control

VS Code hay IDE khác yêu cầu trust workspace trước khi Remote Control truy cập được. Trust workspace khi được nhắc, rồi khởi động lại Remote Control bằng /remote-control. Trong home directory, trust không bao giờ được lưu vì lý do bảo mật - chuyển sang một thư mục dự án và khởi động ở đó.

claude import chưa khả dụng

claude import is not yet available in this build - có thể do bạn chưa chạy phiên nào từ sau khi cài (chưa fetch được feature flag), đang dùng Claude Code qua Amazon Bedrock/Google Cloud/Microsoft Foundry/Claude Platform on AWS (các provider này không fetch feature flag), hoặc đã đặt biến tắt fetch flag như DISABLE_TELEMETRY. Với cài mới, chạy claude một lần, thoát, rồi thử lại claude import. Nếu flag fetching tắt hẳn theo chủ đích, tự cấu hình thủ công: thêm MCP server bằng claude mcp add, tạo CLAUDE.md/skill/subagent cần thiết.

Could not read Claude Code config

Could not read Claude Code config - run claude with no arguments to recover it - chạy claude không tham số, Claude Code phát hiện file hỏng và đề nghị reset; hoặc tự sửa cú pháp JSON trong ~/.claude.json nếu muốn giữ chỉnh sửa thủ công.

Không import được server từ Claude Desktop

Could not import <server>: <reason> - thường do tên server chứa ký tự không hợp lệ (chỉ chấp nhận chữ, số, gạch ngang, gạch dưới). Đổi tên trong claude_desktop_config.json rồi chạy lại claude mcp add-from-claude-desktop, hoặc thêm trực tiếp bằng claude mcp add/claude mcp add-json.

MCP permission prompt tool not found

Error: MCP tool ... (passed via --permission-prompt-tool) not found - kiểm tra server có kết nối bằng claude mcp list, xác nhận tên tool khớp đúng dạng mcp__<server>__<tool>; nếu server cần hơn 30 giây để khởi động, tăng MCP_TIMEOUT.

/security-review fails without origin/HEAD

fatal: ambiguous argument 'origin/HEAD...' khi chạy /security-review - repo thiếu ref origin/HEAD. Tạo nó bằng git remote set-head origin <default-branch> (fetch nhánh trước nếu clone chỉ có một nhánh: git remote set-branches --add origin <branch> rồi git fetch origin), hoặc git fetch origin && git remote set-head origin --auto để tự hỏi remote. Nếu repo chưa có remote, thêm bằng git remote add origin <url> rồi fetch trước khi tạo ref.

Input must be provided khi dùng —print

Input must be provided either through stdin or as a prompt argument when using --print - chạy claude không kèm -p trong terminal thật để dùng interactive; hoặc truyền prompt: claude -p "câu hỏi" hay pipe qua stdin.

Input contained only whitespace

Prompt gửi qua -p, stdin, hay message vào phiên --input-format stream-json/Agent SDK chỉ toàn khoảng trắng, nên không có gì được gửi tới model. Kiểm tra script tạo prompt từ biến/file không bị rỗng trước khi gọi Claude Code.

Diff is too large for ultrareview

Số file/dòng thay đổi vượt giới hạn của /code-review ultra (500 file, 8.000 dòng). Truyền base branch gần hơn (/code-review ultra <branch>) để thu hẹp phạm vi, hoặc chia nhỏ thay đổi thành nhiều branch nhỏ hơn.

Could not find merge-base

/code-review ultra không tìm được merge-base với branch mặc định hoặc branch bạn chỉ định. Truyền base branch tường minh (/code-review ultra <branch>); nếu branch chưa có trong clone, git fetch origin <branch> trước; nếu clone của bạn là shallow clone, chạy git fetch --unshallow origin rồi thử lại.

Your checkout has no branches

Checkout đang ở detached HEAD, không thể bundle cho cloud review. Tạo branch tại commit hiện tại bằng git checkout -b <name> rồi chạy lại /code-review ultra.

Failed to resume the conversation

Transcript hội thoại không nạp được khi dùng --resume hay --continue. Chạy claude --resume <session-id> với ID trong thông báo để thử lại; nếu vẫn fail, claude để bắt đầu phiên mới.

No conversation found with the session ID

ID gõ sai, transcript đã bị dọn dẹp sau retention period (mặc định 30 ngày), phiên chạy trên máy khác (transcript lưu cục bộ), hoặc có bản trùng ID do copy thư mục project. Với phiên interactive, mở claude --resume rồi nhấn Ctrl+A để mở rộng danh sách sang mọi project trên máy. Phiên tạo bằng claude -p hay Agent SDK không hiện trong picker - đối chiếu lại ID với giá trị session_id mà lần chạy gốc đã in ra.

Lỗi plugin

Marketplace đăng ký từ nguồn không tin cậy

Marketplace "<name>" is registered from an untrusted source - một số tên (như claude-community) chỉ dành riêng cho marketplace chính thức của Anthropic. Chạy claude plugin marketplace remove <name> rồi thêm lại marketplace từ nguồn chính thức github.com/anthropics/.

Lệnh plugin tham chiếu user_config

Hook, monitor, hay headersHelper của một plugin tham chiếu ${user_config.*} trong ngữ cảnh sẽ bị shell re-parse lại - không an toàn. Với hook, thêm mảng args để chạy ở exec form (mỗi ${user_config.KEY} thành một argument riêng, không qua shell), hoặc đọc biến môi trường $CLAUDE_PLUGIN_OPTION_<KEY> thay vào đó. Với monitor, đọc giá trị từ file cấu hình thay vì tham chiếu trực tiếp. Với headersHelper, đưa ${user_config.KEY} vào field headers (không bị shell parse) hoặc đọc trong chính helper script.

Plugin archive integrity check failed

Checksum SHA-256 của archive không khớp giá trị đã pin trong marketplace entry - file tại URL đã đổi, tác giả nhập sai digest, hoặc URL phục vụ nhầm file. Nếu bạn là tác giả plugin, tính lại digest đúng file (shasum -a 256 <file> hoặc Get-FileHash -Algorithm SHA256 trên PowerShell) và cập nhật entry. Nếu bạn đang cài, chạy /plugin marketplace update <name> để làm mới catalog rồi cài lại.

Lỗi tool

Agent would be spawned with zero tools

Danh sách tools của subagent/agent resolve về rỗng - Claude Code chặn việc này vì lý do an toàn. Nguyên nhân: entry không nhận diện được (gõ sai tên tool), entry là tool hợp lệ nhưng subagent chạy nền không được dùng (mặc định subagent chạy nền), hoặc entry không khớp tool nào trong phiên hiện tại (ví dụ mcp__github__* nhưng chưa kết nối server GitHub). Sửa lại từng entry thông báo nêu tên; xoá field tools hoàn toàn để kế thừa mọi tool subagent được dùng; với tool chỉ chạy foreground được, tắt fork mode và nhờ Claude chạy subagent ở foreground.

File is covered by a Read deny rule

File bạn cố đọc bị chặn bởi permission settings. Kiểm tra rule permissions.deny, điều chỉnh để cho phép truy cập file cần, hoặc dùng đường dẫn khác không nằm trong deny rule.

Memory index is over its read limit

MEMORY.md vượt quá 200 dòng giới hạn đọc - mọi nội dung sau ngưỡng đó bị bỏ qua âm thầm khi index được nạp lại. Nhờ Claude viết lại: mỗi entry một dòng, chuyển chi tiết sang file theo chủ đề riêng, gộp/bỏ entry cũ. Xem Điều chỉnh memory.

pkill pattern matches the Claude Code process

Một lệnh pkill hay tương tự sẽ chấm dứt chính tiến trình Claude Code. Dùng pattern cụ thể hơn không khớp process Claude Code, hoặc chấm dứt theo PID; để chỉ dừng process con của shell hiện tại, dùng pkill -P $$ ....

Failed to write to a teammate’s inbox

Trong agent team, tin nhắn/permission request/plan approval không ghi được vào inbox của teammate hay team lead - thường do tranh chấp lock tạm thời. Nhờ người gửi gửi lại; kiểm tra dung lượng đĩa còn trống và quyền ghi vào ~/.claude/teams.

Lỗi phiên chạy nền

Commands refused in a background session

Can't open MCP settings while no terminal is attached to this background session - một số lệnh cần terminal đính kèm. Attach vào phiên từ agent view (mục Needs input) rồi chạy lại lệnh, hoặc dùng dạng không cần attach như /mcp reconnect <server>, /mcp enable, /mcp disable.

Write hoặc command bị chặn do path

Claude Code chặn ghi/lệnh khi đường dẫn viết theo dạng không resolve an toàn được (qua symlink chứa .., dạng network-share/UNC, hay thư mục cha không đọc được) hoặc dạng network-shaped trong khi checkout của phiên là local. Thường không cần làm gì - Claude Code tự thấy lỗi và thử lại với đường dẫn trực tiếp, không qua symlink/network path. Nếu bị chặn lặp lại trên cùng file, có thể một symlink đã commit đang trỏ ra ngoài worktree - sửa để Claude thao tác thẳng trên file thật.

This session has no saved transcript

Một phiên chạy nền được tạo mà không lưu transcript hội thoại (bị dừng trước khi có phản hồi đầu tiên). Nếu phiên gốc bạn background từ đó vẫn còn nguyên, resume nó bằng claude --resume; để khởi động lại phiên nền đã dừng, chạy claude respawn <id> với ID trong thông báo, hoặc nhấn Enter hai lần trên dòng phiên đó trong agent view.

Session agent no longer available

This session was running agent '<name>', which is no longer available - file định nghĩa subagent/agent đã bị xoá hoặc đổi tên từ lúc phiên chạy tới giờ. Tạo lại file agent ở .claude/agents/<name>.md (hoặc ~/.claude/agents/ cho agent cá nhân) rồi resume lại, hoặc resume với --agent <name> trỏ tới agent còn tồn tại.

CLAUDE_CODE_PROCESS_WRAPPER launcher errors

launcher '<path>' is not an executable regular file - biến CLAUDE_CODE_PROCESS_WRAPPER trỏ sai. Đặt biến thành đường dẫn tuyệt đối tới một executable kết thúc bằng lệnh exec "$@". Kiểm tra /status (mục Self-exec) hoặc claude daemon status để xem lệnh khởi động đã resolve; sau khi sửa, restart background service bằng claude daemon stop --any.

EUNKNOWN khi khởi động phiên nền

spawn background service: EUNKNOWN: unknown error, uv_spawn - thường gặp trên Windows. Nếu thông báo là “Couldn’t start the session”, nâng cấp lên v2.1.212 trở lên (hoặc chạy claude daemon run ở terminal riêng trước như giải pháp tạm trên bản cũ). Nếu vẫn gặp trên bản mới, nhờ admin Windows allowlist executable Claude Code trong policy hạn chế; nếu service tắt khi đóng terminal, cài PowerShell 7 để service chạy độc lập được.

Lỗi wrapper và IDE

Claude Code process exited with code N

Claude Code CLI thoát với status code khác 0, thường báo hiệu lỗi trong lúc chạy. Thông báo này do chương trình khởi chạy (IDE, Desktop app, hay Agent SDK wrapper) in ra. Trong VS Code, theo link “View output logs” đi kèm; chạy claude trực tiếp trong terminal cùng project để tái hiện lỗi thật; chạy claude doctor để kiểm tra cài đặt/cấu hình.

Could not locate the Claude CLI on PATH

VS Code extension không tìm thấy CLI claude trên PATH. Mở PowerShell mới ngoài VS Code, chạy where.exe claude; nếu không ra path, thêm thư mục cài vào PATH hệ thống (không phải PowerShell profile - extension không đọc profile); nếu có path nhưng lỗi vẫn còn, restart VS Code (extension chỉ đọc PATH lúc khởi động).

Cảnh báo rewind

Restored the code, but skipped files

Thao tác /rewind khôi phục phần lớn file nhưng không khôi phục được một số file - do file là (hoặc đã trở thành) symlink/hard link, thư mục chứa nó đã đổi từ lúc checkpoint, hoặc backup không đọc an toàn được. Chạy /debug trước lần restore kế tiếp để log ghi rõ từng path bị skip (~/.claude/debug/<session-id>.txt); trên macOS/Linux có thể tự tìm bằng find . -type l (symlink) và find . -type f -links +1 (hard link). Nếu file bị skip là link bạn cố ý tạo, nội dung nó không bị đổi - không cần làm gì thêm; nếu không phải, kiểm tra lại nội dung trước khi tin tưởng.

Cảnh báo lưu phiên

Transcript writes are failing

Transcript writes are failing (disk full - ENOSPC) · recent messages may not be saved for resume - sửa nguyên nhân thông báo nêu: giải phóng dung lượng đĩa (ENOSPC), nâng/xoá quota (EDQUOT), khôi phục quyền ghi vào vị trí lưu transcript (EACCES/EPERM/EROFS). Cảnh báo tự hết khi lần ghi kế tiếp thành công, không cần restart - nhưng tin nhắn gửi trong lúc lỗi có thể đã mất khi bạn resume sau này.

Transcript saving off (SKIP_PROMPT_HISTORY)

Transcript saving is off - CLAUDE_CODE_SKIP_PROMPT_HISTORY is set - nếu bạn cố ý đặt biến này, không cần làm gì (phiên sẽ không xuất hiện trong --resume/--continue/lịch sử up-arrow). Nếu không cố ý, gỡ biến khỏi shell/script khởi động rồi bắt đầu phiên mới - tin nhắn đã gửi trước đó không được lưu hồi tố.

Transcript saving off (CHILD_SESSION)

Transcript saving is off - inherited CLAUDE_CODE_CHILD_SESSION marker - phiên được khởi động từ bên trong một phiên Claude Code khác. Nếu cố ý, không cần làm gì. Nếu đây là phiên cấp cao nhất, thoát và khởi động lại với CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1; để sửa vĩnh viễn, gỡ CLAUDE_CODE_CHILD_SESSION khỏi environment của terminal/launcher đó.

Cảnh báo cấu hình

Workspace has not been trusted

Workspace của bạn có permission rule đang bị bỏ qua vì bạn chưa trust nó. Chạy claude trong thư mục đó và chấp nhận trust dialog (dialog vẫn hiện dù thư mục cha đã trust); ở non-interactive mode (-p), tự đặt projects["<path>"].hasTrustDialogAccepted: true trong ~/.claude.json theo đúng key thông báo in ra. Khởi động lại Claude Code sau khi trust để permission rule có hiệu lực.

Is not matched by file permission checks

Write(path) hay NotebookEdit(path) không được permission check cho file nhận diện - chỉ rule Edit(path) mới bao phủ mọi tool sửa file. Thay Write(path)/NotebookEdit(path)/MultiEdit(path) (cũ) bằng Edit(path); thay Glob(path) bằng Read(path) (trừ trong --allowedTools). Sửa tại đúng nguồn thông báo nêu trong ngoặc (file settings hay chính flag --allowed-tools).

The 200K limit isn’t enforced

CLAUDE_CODE_DISABLE_1M_CONTEXT đã đặt nhưng model hiện tại không tự giới hạn ở 200K - phiên có thể phình quá ngưỡng đó. Đặt CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (hoặc setting autoCompactWindow) để auto-compact kích hoạt đúng ngưỡng 200K; nếu model ID không được nhận diện, claude update; nếu muốn dùng trọn context window đầy đủ của model, unset CLAUDE_CODE_DISABLE_1M_CONTEXT.

Unrecognized model ID on a request

[claude-code:unrecognized_model] ghi vào stderr (-p) hoặc debug log (--debug) khi model ID không nằm trong danh sách Claude Code biết - ví dụ alias của một LLM gateway. Nếu cố ý dùng ID đó, thêm entry modelOverrides trong settings ánh xạ một Anthropic model ID sang giá trị đó. Nếu ID mới hơn version hiện tại, claude update; nếu là lỗi gõ, sửa tại nơi bạn đặt nó (--model, ANTHROPIC_MODEL, hay setting model của subagent).

Chất lượng phản hồi

Nếu phản hồi của Claude có vẻ kém hữu ích hay chính xác hơn mong đợi mà không kèm lỗi cụ thể, kiểm tra:

• Xác nhận bạn đang dùng đúng model dự định bằng /status hoặc /model - một lựa chọn /model trước đó hay biến ANTHROPIC_MODEL có thể khiến bạn đang ở model nhỏ hơn dự định; --fallback-model, kiểm tra khả dụng của Bedrock/Google Cloud lúc khởi động, hay automatic model fallback trên Fable 5/Opus 5 cũng có thể tự chuyển model cho một lượt
• Kiểm tra effort level bằng /effort và nâng lên cho việc debug/thiết kế khó - mặc định khác nhau theo model
• Kiểm tra /context xem có gần chạm giới hạn context window không - phản hồi giảm chất lượng khi context đầy; /compact ở điểm dừng tự nhiên hoặc /clear nếu cần
• File CLAUDE.md lớn/lỗi thời và định nghĩa MCP tool không dùng tới chiếm context và có thể lái phản hồi lệch hướng - /doctor gắn cờ file memory quá khổ, /context hiện token usage của MCP tool
• Thử phiên mới với /clear để loại trừ khả năng lịch sử hội thoại ảnh hưởng phản hồi

Báo lỗi

Với các loại sự cố có trang riêng, xem trang đó trước: MCP server không kết nối/xác thực được → MCP; hook script lỗi hoặc chặn tool → Hooks; lỗi quyền/filesystem lúc cài → Khắc phục sự cố cài đặt.

Chạy /feedback trong Claude Code để gửi transcript kèm mô tả cho Anthropic (yêu cầu đã xác thực; lệnh cũng đề nghị mở sẵn GitHub issue). Trên Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, hay khi không có credential Anthropic, /feedback lưu một archive cục bộ để bạn gửi qua đại diện tài khoản Anthropic của mình thay vào đó. Chạy claude doctor từ shell để chẩn đoán cài đặt read-only, hoặc /doctor trong phiên để tìm và tự sửa vấn đề cấu hình. Kiểm tra status.claude.com để biết sự cố đang diễn ra, hoặc tìm issue đã có trên GitHub.

Chú ý

Nhiều chi tiết trong trang này (số phiên bản, tên biến môi trường, ngưỡng cụ thể, các biến thể thông báo lỗi) thay đổi thường xuyên giữa các bản Claude Code và không được liệt kê đầy đủ 100% - đối chiếu với tài liệu gốc nếu cần độ chính xác cao hoặc không tìm thấy thông báo lỗi của bạn ở đây.

Nguồn

Dịch và biên soạn từ Error reference.