SpyBara
Go Premium

errors.md 2026-07-09 23:58 UTC to 2026-07-10 17:00 UTC

526 added, 301 removed.

2026
Sat 11 19:03 Fri 10 17:00 Thu 9 23:58 Wed 8 16:02 Tue 7 16:02 Mon 6 23:57 Sat 4 03:01 Fri 3 23:00 Thu 2 23:59 Wed 1 21:01

錯誤參考

查詢 Claude Code 執行時錯誤訊息，了解每個錯誤的含義及修復方法。

本頁列出 Claude Code 顯示的執行時錯誤及如何從每個錯誤中恢復，以及當回應似乎有問題但沒有錯誤時要檢查的內容。如需安裝錯誤（例如 command not found 或設定期間的 TLS 失敗），請參閱 Troubleshoot installation and login。

這些錯誤和恢復命令適用於 CLI、Desktop app 和 Claude Code on the web，因為這三者都包裝相同的 Claude Code CLI。如需特定表面的問題，請參閱該表面頁面上的疑難排解部分。

尋找您的錯誤

將您在終端中看到的訊息與下方的部分相符。

訊息 部分
API Error: 500 Internal server error Server errors
API Error: Repeated 529 Overloaded errors Server errors
Request timed out Server errors，或如果訊息提及您的網際網路連線，則為 Network
Server error mid-response. The response above may be incomplete. Server errors
Connection closed mid-response / Response stalled mid-stream Server errors
<model> is temporarily unavailable, so auto mode cannot determine the safety of... Server errors
Auto mode could not evaluate this action and is blocking it for safety Server errors
Auto mode classifier transcript exceeded context window Server errors
Agent terminated early due to an API error Server errors
You've hit your session limit / You've hit your weekly limit Usage limits
Usage credits required for 1M context Usage limits
Server is temporarily limiting requests Usage limits
Request rejected (429) Usage limits
Credit balance is too low Usage limits
Not logged in · Please run /login Authentication
Could not resolve authentication method Authentication
Invalid API key Authentication
This organization has been disabled Authentication
Your organization has disabled API key authentication Authentication
Your organization has disabled Claude subscription access Authentication
Routines are disabled by your organization's policy Authentication
Remote Control is only available when using Claude via api.anthropic.com Authentication
OAuth token revoked / OAuth token has expired Authentication
does not meet scope requirement user:profile Authentication
AWS credentials expired or invalid Authentication
AWS authentication failed Authentication
Unable to connect to API Network
Waiting for API response · will retry in Automatic retries，或如果持續發生，則為 Network
SSL certificate verification failed Network
SSL certificate error (...) during login or startup Network
403 with x-deny-reason: host_not_allowed in a cloud or routine session Network
Couldn't reconnect to your Remote Control session Network
Prompt is too long Request errors
Error during compaction: Conversation too long Request errors
Request too large Request errors
Image was too large Request errors
Unable to resize image Request errors
PDF too large / PDF is password protected Request errors
Extra inputs are not permitted Request errors
There's an issue with the selected model Request errors
Model ... is not a recognized model id Request errors
Claude Opus is not available with the Claude Pro plan Request errors
Model ... is restricted by your organization's settings Request errors
thinking.type.enabled is not supported for this model Request errors
max_tokens must be greater than thinking.budget_tokens Request errors
API Error: 400 due to tool use concurrency issues Request errors
Claude Code is unable to respond to this request, which appears to violate our Usage Policy Request errors
<model> has safety measures that flagged this message for a cybersecurity topic Request errors
Installation was killed before it could finish (exit code 137) Installation errors
The connection dropped while downloading the update Installation errors
Download timed out: exceeded the total deadline Installation errors
--bg and --print conflict Command-line errors
Error: --json-schema is not a valid JSON Schema Command-line errors
Could not import <server>: <reason> Command-line errors
Marketplace "<name>" is registered from an untrusted source Plugin errors
Ignoring N permissions.allow entries from ... this workspace has not been trusted Configuration warnings
回應品質似乎低於平常 Response quality

自動重試

Claude Code 在向您顯示錯誤之前會重試暫時性失敗。伺服器錯誤、過載回應、請求逾時、臨時 429 節流和中斷的連線都會以指數退避方式重試最多 10 次。{/* min-version: 2.1.198 /}自 v2.1.198 起，這涵蓋在任何可見輸出串流之前在回應中途中斷的連線：Claude Code 使用相同的退避重新發出請求，轉向繼續而不是停止並出現連線錯誤。{/ min-version: 2.1.199 */}自 v2.1.199 起，不帶您計畫配額標頭的臨時 429 節流在您使用 claude.ai 訂閱登入時也會重試；較早的版本僅針對 API 金鑰和 Enterprise 登入重試它們。

有兩個失敗類別不會重試，因為重試無法成功：

  • {/* min-version: 2.1.199 */}自 v2.1.199 起，TLS 憑證驗證失敗（例如 TLS 檢查代理、遺失的 NODE_EXTRA_CA_CERTS 套件或過期的憑證）在第一次嘗試時失敗，因此修復會立即出現，而不是在完整重試預算之後。請參閱 SSL certificate errors。暫時性 TLS 條件（例如握手逾時）仍會重試。
  • {/* min-version: 2.1.199 */}自 v2.1.199 起，在 Claude 已經串流可見輸出後到達的伺服器錯誤會保留部分回應並附加 incomplete-response notice，而不是重試，因為重新執行請求可能會執行相同的工具兩次。較早的版本會捨棄部分輸出並將轉向報告為錯誤。

重試時，微調器會在錯誤標籤後顯示 Retrying in Ns · attempt x/y 倒數計時。標籤命名第一次嘗試的特定原因，以便您可以立即採取行動的失敗：網路已關閉、TLS 握手失敗或您達到速率限制。對於其他錯誤，它最初讀取 API error。{/* min-version: 2.1.198 */}自 v2.1.198 起，它會切換到第三次嘗試的特定原因，或在 CLAUDE_CODE_MAX_RETRIES 允許少於三次時的最後一次嘗試；較早的版本僅在最後一次嘗試時切換。

{/* min-version: 2.1.198 */}自 v2.1.198 起，通常的微調器提示在重試期間被抑制。一旦錯誤原因被揭示，如果失敗是 529 過載，倒數計時下方的行也會命名檢查服務狀態的位置：Anthropic API 上的 status.claude.com，或其他配置上提供者或閘道主機命名的位置。

{/* min-version: 2.1.185 */}如果在請求仍待處理時，回應串流上 20 秒內沒有資料到達，微調器會在任何重試開始之前顯示 Waiting for API response · will retry in … · check your network。請求尚未失敗：倒數計時會執行到 Claude Code 中止停滯連線並重試的位置，因此一旦資料恢復或重試成功，橫幅就會自動清除。自 v2.1.185 起，閾值為 20 秒；較早的版本會在 10 秒後顯示橫幅，措辭不同。如果它在每次嘗試時都重新出現，請將其視為網路問題。

當您看到本頁上的其中一個錯誤時，這些重試已經用盡，除非它屬於不會重試的類別，例如憑證驗證失敗。您可以使用這些環境變數調整行為：

變數 預設值 效果
CLAUDE_CODE_MAX_RETRIES 10 重試次數。{/* min-version: 2.1.186 /}自 v2.1.186 起上限為 15；{/ min-version: 2.1.199 */}自 v2.1.199 起 CLAUDE_CODE_RETRY_WATCHDOG 提高預設值並移除上限。降低它以在指令碼中更快地顯示失敗。
CLAUDE_CODE_RETRY_WATCHDOG 未設定 在 CI 工作等無人值守的工作階段中設定為 1，以無限期重試 429 和 529 容量錯誤，而不是在 CLAUDE_CODE_MAX_RETRIES 次嘗試後失敗。{/* min-version: 2.1.199 */}自 v2.1.199 起，它也提高了其他暫時性錯誤（例如伺服器錯誤、逾時和中斷的連線）的預設重試計數至 300，大約三小時的退避，並在您明確設定該變數時移除 CLAUDE_CODE_MAX_RETRIES 的上限 15。
API_TIMEOUT_MS 600000 每個請求的逾時（毫秒）。為慢速網路或代理提高它。

伺服器錯誤

這些錯誤來自推論提供者，而非您的帳戶或請求。在 Anthropic API 上，這表示 Anthropic 基礎設施。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自訂閘道上，這表示該提供者的基礎設施。

API 錯誤：500 內部伺服器錯誤

Claude Code 會顯示任何 5xx 回應的狀態碼和 API 的錯誤訊息。下面的範例顯示 Anthropic API 上的 500 回應：

API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

結尾的句子會指出要檢查服務健康狀態的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置會指出該提供者的服務狀態。自訂 ANTHROPIC_BASE_URL 會指出閘道主機。

這表示 API 內部發生了意外故障。它不是由您的提示、設定或帳戶造成的。

該怎麼做：

  • 檢查 status.claude.com 或訊息中指名的提供者狀態頁面，查看是否有活躍的事件
  • 等待一分鐘，然後再次傳送您的訊息。您的原始訊息仍在對話中，所以對於較長的提示，您可以輸入 try again 而不是貼上整個內容。
  • 如果錯誤持續出現且沒有發佈的事件，請執行 /feedback 以便 Anthropic 可以使用您的請求詳細資訊進行調查。如果您的環境中無法使用 /feedback，請參閱報告錯誤。

API 錯誤：重複的 529 超載錯誤

API 在所有使用者中暫時達到容量上限。Claude Code 在顯示此訊息之前已經重試了多次：

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

結尾的句子因提供者而異，方式與上面的 500 錯誤相同。

529 不是您的使用限制，也不會計入您的配額。

該怎麼做：

  • 檢查 status.claude.com 或訊息中指名的提供者狀態頁面，查看是否有容量通知
  • 幾分鐘後再試一次
  • 執行 /model 並切換到不同的模型以繼續工作，因為容量是按模型追蹤的。當某個模型負載特別高時，Claude Code 會提示您執行此操作，例如 Opus is experiencing high load, please use /model to switch to Sonnet。

請求逾時

API 在連線截止期限之前沒有回應。

Request timed out

這可能在高負載期間或模型生成非常大的回應時發生。預設請求逾時為 10 分鐘。

該怎麼做：

  • 重試請求
  • 對於長時間執行的任務，將工作分解為較小的提示
  • 如果是緩慢的網路或代理造成的，請按照自動重試中的說明提高 API_TIMEOUT_MS
  • 如果逾時頻繁且您的網路狀況良好，請參閱下面的網路和連線錯誤

上面的回應可能不完整

串流回應在 Claude 已經產生可見輸出後失敗。重新傳送請求可能會執行相同的工具呼叫兩次，所以 Claude Code 會保留已經串流的內容，並改為附加此通知，而不是捨棄該輪次。您看到的變體會指出原因：

API Error: Server error mid-response. The response above may be incomplete.
API Error: Connection closed mid-response. The response above may be incomplete.
API Error: Response stalled mid-stream. The response above may be incomplete.
  • {/* min-version: 2.1.199 */}}Server error mid-response：中途串流超載或 5xx 伺服器錯誤。此變體需要 Claude Code v2.1.199 或更新版本；在此之前，該情況會捨棄部分輸出並將整個輪次報告為錯誤。
  • Connection closed mid-response：連線中斷。
  • Response stalled mid-stream：串流停止傳送資料。

該怎麼做：

  • 閱讀已串流的回應。沒有任何內容遺失，但最後的句子或工具呼叫可能缺失。
  • 回覆 continue 以讓 Claude 從停止的地方繼續
  • 如果相同的錯誤在任何可見輸出之前出現，Claude Code 會重試請求而不是完成它。請參閱自動重試。

自動模式無法判斷動作的安全性

自動模式用來分類動作的模型無法做出決定，所以自動模式沒有自動批准該動作。您看到的訊息取決於分類器失敗的原因。

在您的工作目錄內的讀取、搜尋和編輯會跳過分類器，所以它們在所有這些情況下都能繼續工作。

當分類器模型超載時：

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.

該怎麼做：

  • 幾秒鐘後重試；Claude 會看到相同的訊息，通常會自動重試
  • 如果重試持續失敗，請繼續執行唯讀任務，稍後再回到被阻止的動作
  • 這是暫時的，與自動模式資格無關；您不需要變更設定

當分類器傳回無法解析的回應時：

Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

該怎麼做：

  • 重試該動作；這通常在下一次嘗試時成功
  • 執行 claude --debug 並重複該動作以在偵錯日誌中查看基礎分類器回應

當單獨的 API 安全檢查因為較早的對話內容而阻止了分類器請求時：

Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

該怎麼做：

  • 這不是關於您的動作的決定。您對話中已有的內容在自動模式將對話傳送給分類器時觸發了 API 上的安全篩選器
  • 重試無法幫助；相同的對話內容會再次觸發篩選器
  • 切換到不同的權限模式，以便在出現提示時批准該動作，或開始一個沒有觸發內容的新對話

當對話大小超過分類器的上下文視窗時：

Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

在互動式工作階段中，自動模式會為該動作回退到正常的權限提示，以便您可以手動批准或拒絕它。在非互動式模式中，執行會中止，因為文字記錄只會增長，重試無法成功。

該怎麼做：

  • 在出現的提示中批准或拒絕該動作
  • 執行 /compact 以減少對話大小，以便後續動作再次適應分類器視窗

代理因 API 錯誤而提前終止

{/* min-version: 2.1.199 */}子代理的 API 請求終止失敗，例如因為達到使用限制或伺服器錯誤的重試用盡，所以子代理在完成其任務之前停止。此訊息需要 Claude Code v2.1.199 或更新版本；在此之前，API 錯誤文字被傳回給 Claude，就像它是子代理的結果一樣。

Agent terminated early due to an API error: <error detail>

該怎麼做：

  • 將冒號後的錯誤詳細資訊與此頁面上的自己的部分相符，例如使用限制或伺服器錯誤，並遵循該部分的步驟
  • 一旦基礎錯誤清除，請要求 Claude 重試任務或恢復子代理

當速率限制、超載或伺服器錯誤中斷已經產生文字輸出的前景子代理時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。{/* min-version: 2.1.200 */}只有工具呼叫輸出的子代理也會收到此錯誤；在 v2.1.199 中，該形狀改為傳回空的部分結果。請參閱子代理中的 API 錯誤。

使用限制

這些錯誤表示與您的帳戶或方案相關的配額已達到。它們與伺服器錯誤不同，伺服器錯誤會影響所有人。

您已達到工作階段限制

訂閱方案包括滾動使用額度。當額度用完時，您會看到以下其中一條訊息：

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

Claude Code 會阻止進一步的請求，直到訊息中顯示的重設時間。

該怎麼做：

  • 等待錯誤訊息中顯示的重設時間
  • 執行 /usage 以查看您的方案限制及其重設時間
  • 執行 /usage-credits 以在 Pro 和 Max 上購買額外使用額度，或在 Team 和 Enterprise 上向您的管理員請求。請參閱付費方案的使用額度以了解如何計費。
  • 若要升級您的方案以獲得更高的基本限制，請參閱 claude.com/pricing

若要在達到限制之前監控您的剩餘額度，請將 rate_limits 欄位新增至自訂狀態列，或在桌面應用程式中按一下模型選擇器旁的使用量環。

1M 上下文需要使用額度

選定的模型使用 1M 令牌擴展上下文視窗，而您的方案僅透過使用額度包含它。

API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

這是一項權利檢查，而不是配額耗盡。即使您的工作階段和每週額度仍有容量，它也會觸發。請參閱擴展上下文以了解哪些方案直接包含 1M 上下文，哪些需要使用額度。

{/* min-version: 2.1.172 */}當此錯誤在對話中途出現，因為上下文增長超過 200K 令牌時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並在之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 /compact）上重複出現；在這些版本上執行 /clear 以恢復。以下步驟適用於您明確選擇 [1m] 模型的情況。

該怎麼做：

  • 執行 /model 並選擇不帶 [1m] 後綴的變體以回退到標準上下文視窗
  • 執行 /usage-credits 以在 Pro 和 Max 上開啟 1M 變體的計量計費，或在 Team 和 Enterprise 上向您的管理員請求
  • 如果 /model 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱選定的模型有問題以按優先順序檢查配置位置。
  • 若要從模型選擇器中完全移除 1M 變體，請設定 CLAUDE_CODE_DISABLE_1M_CONTEXT=1

伺服器暫時限制請求

API 應用了與您的方案配額無關的短期節流。

API Error: Server is temporarily limiting requests (not your usage limit)

Claude Code 透過真實限制回應所攜帶的統一配額標頭的缺失來區分這些與您的方案限制。{/* min-version: 2.1.199 */}自 v2.1.199 起，無論您如何驗證，這都會自動重試並進行退避，然後才會顯示。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時失敗；只有 API 金鑰和 Enterprise 登入會重試它。

該怎麼做：

請求被拒絕 (429)

您已達到為 API 金鑰、Amazon Bedrock 專案或 Google Cloud 專案配置的速率限制。

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

尾部句子命名檢查服務健康狀況的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置會命名該提供者的服務狀態，而不是 Anthropic 狀態頁面。自訂 ANTHROPIC_BASE_URL 會命名閘道主機。

該怎麼做：

  • 執行 /status 並確認作用中的認證是您預期的認證。環境中的流浪 ANTHROPIC_API_KEY 可能會透過低階金鑰而不是您的訂閱來路由請求。
  • 檢查您的提供者主控台以了解作用中的限制，並在需要時請求更高的層級
  • 對於 Anthropic API 金鑰，請參閱速率限制參考以了解層級如何運作以及如何設定每個工作區的上限
  • 降低並行性：降低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY、避免執行許多平行子代理，或使用 /model 切換到較小的模型以進行大量指令碼執行

信用額度餘額過低

您的 Console 組織已用完預付信用額度。

Credit balance is too low

該怎麼做：

  • 在 platform.claude.com/settings/billing 新增信用額度，並考慮在那裡啟用自動重新載入，以便在餘額達到零之前進行補充
  • 如果您有 Pro、Max、Team 或 Enterprise 方案，請使用 /login 切換到訂閱驗證
  • 在 Console 中設定每個工作區的支出上限，以防止單一專案耗盡組織餘額。請參閱有效管理成本。

驗證錯誤

這些錯誤表示 Claude Code 無法向 API 證明您的身份。隨時執行 /status 以查看目前使用的認證方式。

未登入

此工作階段沒有有效的認證方式可用。

Not logged in · Please run /login

應該怎麼做：

  • 執行 /login 以使用您的 Claude 訂閱或 Console 帳戶進行驗證
  • 如果您預期使用環境變數進行驗證，請確認 ANTHROPIC_API_KEY 已在啟動 claude 的 shell 中設定並匯出
  • 對於無法進行互動式登入的 CI 或自動化環境，請設定一個 apiKeyHelper 指令碼，在啟動時取得金鑰
  • 請參閱驗證優先順序以了解當存在多個認證方式時，Claude Code 使用哪一個

如果系統反覆提示您登入，請參閱未登入或權杖已過期以取得系統時鐘和 macOS Keychain 的修復方法。

無法解析驗證方法

工作階段到達 API 用戶端時沒有任何認證方式。這會出現在背景工作階段、雲端工作階段和 Agent SDK 環境中，其中互動式登入檢查在第一個請求之前不會執行。

Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

{/* min-version: 2.1.174 */}在 v2.1.174 之前，指派給閒置預初始化背景工作程序的背景或雲端工作階段即使已設定有效認證方式也可能以此方式失敗。請升級以恢復。在目前版本中，此錯誤表示背景工作程序沒有可用的認證方式。

應該怎麼做：

  • 如果此錯誤出現在背景或雲端工作階段中且您的認證方式已設定，請升級至 v2.1.174 或更新版本
  • 確認 ANTHROPIC_API_KEY、CLAUDE_CODE_OAUTH_TOKEN 或您的雲端提供者認證方式已在啟動背景工作程序的環境中設定，而不僅在您的互動式 shell 中
  • 對於 Agent SDK，請參閱驗證設定
  • 在相同環境中的互動式工作階段中執行 /status 以確認哪個認證方式來源可以解析

無效的 API 金鑰

ANTHROPIC_API_KEY 環境變數或 apiKeyHelper 指令碼傳回的金鑰被 API 拒絕。

Invalid API key · Fix external API key

應該怎麼做：

  • 檢查是否有拼寫錯誤，並確認該金鑰未在 Console 中被撤銷
  • 在相同的 shell 中執行 env | grep ANTHROPIC。direnv、dotenv shell 外掛程式和 IDE 終端等工具可能會從您專案中的 .env 檔案載入過時的金鑰，而您並未明確設定它
  • 取消設定 ANTHROPIC_API_KEY 並執行 /login 以改用訂閱驗證
  • 如果金鑰來自 apiKeyHelper 指令碼，請直接執行該指令碼以確認它在 stdout 上列印有效的金鑰
  • 執行 /status 以確認 Claude Code 實際使用的認證方式來源

此組織已被停用

來自已停用 Console 組織的過時 ANTHROPIC_API_KEY 正在覆蓋您的訂閱登入。

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials
API Error: 400 ... This organization has been disabled.

環境變數優先於 /login，因此即使您有有效的 Pro 或 Max 訂閱，在 shell 設定檔中匯出或從 .env 檔案載入的金鑰也會被使用。在非互動模式 (-p) 中，當金鑰存在時總是使用該金鑰。

應該怎麼做：

  • 在目前 shell 中取消設定 ANTHROPIC_API_KEY 並從您的 shell 設定檔中移除它，然後重新啟動 claude
  • 之後執行 /status 以確認使用中的認證方式是您的訂閱
  • 如果未設定環境變數且錯誤仍然存在，則已停用的組織是與您的 /login 相關聯的組織。請聯絡支援或使用不同的帳戶登入。

您的組織已停用 API 金鑰驗證

此訊息需要 Claude Code v2.1.169 或更新版本。您的 Console 組織管理員已關閉 API 金鑰驗證，因此 API 拒絕了 Claude Code 正在傳送的金鑰。· 之後的恢復提示會根據金鑰的來源而有所不同：

Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

環境變數和 apiKeyHelper 優先於 /login，因此當其中任一個仍在提供金鑰時，單獨執行 /login 無法幫助。請參閱驗證優先順序。

應該怎麼做：

  • 如果訊息提及 ANTHROPIC_API_KEY，請在目前 shell 中取消設定它，並從您的 shell 設定檔或 .env 檔案中移除它，然後重新啟動 claude
  • 如果訊息提及 apiKeyHelper，請從您的 settings.json 中移除 apiKeyHelper 設定
  • 執行 /login 以使用您的 claude.ai 帳戶登入
  • 之後執行 /status 以確認使用中的認證方式是您的訂閱而不是 API 金鑰
  • 如果您需要 API 金鑰驗證進行自動化，請要求您的組織管理員在 Console 中重新啟用它

您的組織已停用 Claude 訂閱存取

您的 Claude 組織不允許使用訂閱登入來登入 Claude Code。使用相同帳戶再次執行 /login 會傳回相同的錯誤。

Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

這是伺服器端組織設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。

Agent SDK 和 -p 非互動模式將此顯示為 oauth_org_not_allowed 錯誤代碼。

應該怎麼做：

  • 要求您的管理員為您的組織啟用 Claude Code 存取
  • 使用 Console API 金鑰而不是您的訂閱進行驗證。請參閱 Claude Console 驗證以進行設定。
  • 如果您是管理員且看不到啟用存取的選項，請聯絡 Anthropic 支援

您的組織政策已停用例行工作

您的 Team 或 Enterprise 組織中的擁有者已在組織層級關閉例行工作。當您嘗試建立或執行例行工作時（包括從 /schedule 和 claude.ai/code 上的例行工作 UI），會出現此錯誤。

Routines are disabled by your organization's policy.

這是伺服器端設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。

應該怎麼做：

Remote Control 需要 Anthropic API

工作階段未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端供 Remote Control 配對。

Remote Control is only available when using Claude via api.anthropic.com.

這會出現在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}從 v2.1.196 開始，當 ANTHROPIC_BASE_URL 指向 api.anthropic.com 以外的主機（例如 LLM 閘道或代理）時，即使您使用 claude.ai 登入，也會出現此訊息。

應該怎麼做：

  • 取消設定 ANTHROPIC_BASE_URL 並重新啟動工作階段，或從直接與 Anthropic API 通訊的工作階段啟動 Remote Control
  • 對於此訊息和其他 Remote Control 啟動訊息，請參閱疑難排解 Remote Control

OAuth 權杖已撤銷或已過期

您儲存的登入不再有效。撤銷的權杖表示您已在所有地方登出或管理員移除了存取；過期的權杖表示自動重新整理在工作階段中途失敗。

OAuth token revoked · Please run /login
OAuth token has expired · Please run /login
API Error: 401 ... authentication_error

應該怎麼做：

  • 執行 /login 以重新登入
  • 如果在同一工作階段中重新驗證後錯誤仍然出現，請先執行 /logout 以完全清除儲存的權杖，然後執行 /login
  • 對於跨啟動的重複登入提示，請參閱疑難排解中的系統時鐘和 macOS Keychain 檢查
  • 對於其他失敗（包括 403 Forbidden 和 OAuth 瀏覽器問題），請參閱登入和驗證

OAuth 範圍要求

儲存的權杖早於較新功能所需的權限範圍。您最常從 /usage 和狀態列使用量指示器看到此訊息：

OAuth token does not meet scope requirement: user:profile

應該怎麼做：

  • 執行 /login 以取得具有目前範圍的新權杖。您不需要先登出。

AWS 認證方式已過期或無效

{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 awsAuthRefresh 時出現。您的 AWS 工作階段權杖已過期或被拒絕，Claude Code 已執行的自動重新整理未產生 API 接受的認證方式。它會出現在來自 Claude Platform on AWS 或 Mantle 端點 的 401 上，這是這些提供者報告過期安全權杖的方式。

中間的動作提示會命名您設定中的 awsAuthRefresh 命令，因此會有所不同。穩定的部分是前導的 AWS credentials expired or invalid：

AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

如果未設定 awsAuthRefresh，相同的 401 會改為顯示通用的 Please run /login 訊息，該訊息無法重新整理 AWS 認證方式。

應該怎麼做：

  • 在另一個終端中執行訊息中命名的 awsAuthRefresh 命令（例如 aws sso login --profile myprofile）並完成瀏覽器登入，然後重試
  • 在互動式工作階段中，執行 /login，選擇 3rd-party platform，然後在 Using 3rd-party platforms 下選擇 Claude Platform on AWS · refresh credentials 以執行相同的命令而無需重新啟動 Claude Code。請參閱設定 AWS 認證方式
  • 如果重新整理命令成功後錯誤仍然重複出現，請在相同的 shell 和設定檔中使用 aws sts get-caller-identity 確認身份在 Claude Code 外部有效

AWS 驗證失敗

{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 awsAuthRefresh 時出現。您的 AWS 提供者傳回了 403，或 Amazon Bedrock 傳回了 401。

Claude Code 無法判斷您遇到了哪個原因。Amazon Bedrock 將過期的安全權杖報告為 403，但 403 也是它報告授權拒絕的方式，例如來自遺失 IAM 權限或未為您的帳戶啟用的模型的 AccessDeniedException。

來自 Amazon Bedrock 的 401 也會落在此處而不是在 AWS 認證方式已過期或無效 下，因為 Amazon Bedrock 不會將過期的權杖報告為 401。來自該端點的 401 通常來自請求路徑中的其他內容，例如公司代理。

認證方式重新整理可以修復過期的權杖，無法修復其他原因，因此訊息提供了兩者：

AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

中間的動作提示會命名您設定中的 awsAuthRefresh 命令，因此會有所不同。穩定的部分是前導的 AWS authentication failed。

應該怎麼做：

  • 執行訊息中命名的 awsAuthRefresh 命令或 aws sso login，以防過期的認證方式是原因
  • 如果您的認證方式是最新的，請確認 IAM 配置 中的 IAM 權限已附加到您使用的身份，且所選模型已為您的帳戶和區域啟用
  • 執行 aws sts get-caller-identity 以確認您的請求使用哪個身份；過時的 AWS_PROFILE 或預設設定檔是權限不匹配的常見原因

網路和連線錯誤

這些錯誤表示來自 Claude Code 的網路請求無法到達其目的地。它們通常源自您的本機網路、代理伺服器或防火牆，或雲端環境的網路政策。

無法連線到 API

與 API 的 TCP 連線失敗或從未完成。

Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API (ECONNRESET)
Unable to connect to API (ETIMEDOUT)
fetch failed
Request timed out. Check your internet connection and proxy settings

常見原因包括沒有網際網路存取、阻止 api.anthropic.com 的 VPN，或未設定的必要公司代理伺服器。

該怎麼做：

  • 透過在同一個 shell 中執行 curl -I https://api.anthropic.com 來確認您可以到達 API 主機。在 Windows PowerShell 上使用 curl.exe -I https://api.anthropic.com，以免使用內建的 Invoke-WebRequest 別名。
  • 如果您在公司代理伺服器後面，請在啟動 Claude Code 前設定 HTTPS_PROXY，並參閱網路設定
  • 如果您透過 LLM 閘道或中繼站路由，請將 ANTHROPIC_BASE_URL 設定為其位址。請參閱將 Claude Code 連線到 LLM 閘道以取得設定說明。
  • 確保您的防火牆允許網路存取需求中列出的主機
  • 間歇性故障會自動重試；持續性故障指向本機網路問題

如果 curl 成功但 Claude Code 仍然失敗，原因通常是執行時間和網路之間的某些東西，而不是網路本身：

  • 在 Linux 和 WSL 上，檢查 /etc/resolv.conf 是否有無法到達的名稱伺服器。特別是 WSL 可能會從主機繼承損壞的解析器。
  • 在 macOS 上，已斷開連線或卸載的 VPN 用戶端可能會留下隧道介面或路由規則。檢查 ifconfig 是否有過時的 utun 介面，並在系統設定中移除 VPN 的網路擴充功能。
  • Docker Desktop 和類似的容器執行時間可能會攔截出站流量。結束它們並重試以排除此可能性。

SSL 憑證錯誤

您網路上的代理伺服器或安全設備正在用其自己的憑證攔截 TLS 流量，而 Claude Code 不信任它。

Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates
Unable to connect to API: Self-signed certificate detected

{/* min-version: 2.1.199 */}自 v2.1.199 起，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整重試預算後出現。較早的版本在顯示它之前會花費幾分鐘重試。暫時性 TLS 條件（例如握手逾時）仍會重試。

在 /login 和啟動連線檢查期間，同樣的失敗會以 OpenSSL 代碼和內聯修復報告：

SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

該怎麼做：

  • 匯出您組織的 CA 套件，並使用 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem 將 Claude Code 指向它
  • 請參閱網路設定以取得完整設定說明
  • 不要設定 NODE_TLS_REJECT_UNAUTHORIZED=0，這會完全停用憑證驗證

雲端工作階段中不允許的主機

來自雲端工作階段或例行程序的出站 HTTP 請求被環境的網路政策阻止。

HTTP 403
x-deny-reason: host_not_allowed

您也可能看到與目的地實際憑證不符的 TLS 憑證。雲端環境透過代理伺服器路由出站流量以強制執行網路政策，因此不符的憑證表示代理伺服器終止了連線，而不是目的地。

這不是用戶端網路問題。雲端工作階段和例行程序在沙箱環境內執行，其出站流量被篩選到環境的允許清單。預設環境使用信任存取，允許預設允許清單的套件登錄、雲端提供者 API、容器登錄和常見開發網域，但阻止其他所有內容。

該怎麼做：

  • 開啟例行程序進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱（例如預設）的雲端圖示以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。
  • 在更新雲端環境對話方塊中，將網路存取從信任變更為自訂，然後將被阻止的網域新增到允許的網域。每行輸入一個網域。勾選也包含常見套件管理員的預設清單以在自訂網域旁保留預設允許清單。如果您想要不受限制的存取，請改為選擇完整。
  • 按一下儲存變更。下一次執行會使用更新的允許清單。

請參閱網路存取以取得存取層級和預設允許清單。本機 CLI 工作階段不受此政策影響。

無法重新連線到您的遠端控制工作階段 

Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

使用 claude --resume 或 claude --continue 恢復會重新連線到該對話中記錄的遠端控制工作階段。此訊息表示重新連線因可能是暫時性的原因（例如網路中斷或伺服器錯誤）而失敗，因此 Claude Code 無法確認遠端工作階段是否仍然存在。您的本機工作階段會繼續執行，但不使用遠端控制。

該怎麼做：

  • 執行 /remote-control 以重試連線
  • 啟動 Claude Code 時不使用 --resume 以建立新的遠端控制工作階段
  • 如需其他遠端控制啟動訊息，請參閱遠端控制疑難排解

當伺服器確認前一個工作階段不再存在時，您不會看到此訊息；Claude Code 在這種情況下會建立一個新的工作階段。{/* min-version: 2.1.200 */}在 v2.1.200 之前，任何重新連線失敗都會建立新的遠端控制工作階段，這在 claude.ai/code 的工作階段清單中留下額外的工作階段。

請求錯誤

這些錯誤與您的請求內容有關。大多數來自 API 在拒絕請求後的回應；少數是由 Claude Code 在發送任何請求之前在本地產生的。

提示詞過長

對話加上附加檔案超過了模型的上下文視窗。

Prompt is too long

該怎麼做：

  • 執行 /compact 來總結早期的回合並釋放空間，或執行 /clear 來重新開始
  • 執行 /context 來查看視窗消耗的詳細分解：系統提示詞、工具、記憶檔案和訊息
  • 使用 /mcp disable <name> 停用您未使用的 MCP 伺服器，以從上下文中移除其工具定義
  • 修剪大型 CLAUDE.md 記憶檔案，或將指令移至路徑範圍規則，這些規則只在相關時載入
  • 子代理繼承父工作階段中的每個 MCP 工具定義，這可能會在第一個回合之前填滿其上下文視窗。在生成子代理之前停用您未使用的 MCP 伺服器。
  • 自動壓縮預設為開啟，通常可防止此錯誤。如果您已設定 DISABLE_AUTO_COMPACT，請重新啟用它或在視窗填滿之前手動執行 /compact。

請參閱探索上下文視窗以取得上下文如何填滿的互動式檢視。

壓縮期間出錯：對話過長

/compact 本身失敗，因為沒有足夠的可用上下文來保存它產生的摘要。

Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

當視窗在自動壓縮觸發時已滿，或當您在看到 Prompt is too long 後執行 /compact 時，可能會發生這種情況。

該怎麼做：

  • 按 Esc 兩次以開啟訊息清單並回溯幾個回合。這會從上下文中移除最近的訊息。然後再次執行 /compact。
  • 如果回溯沒有釋放足夠的空間，執行 /clear 以開始新的工作階段。您之前的對話會被保留，可以使用 /resume 重新開啟。

請求過大

原始請求主體在標記化之前超過了 API 的位元組限制，通常是因為貼上了大型檔案或附件。

Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.

這是 HTTP 請求的大小限制，與上下文視窗限制分開。

該怎麼做：

  • 按 Esc 兩次並回溯到添加超大內容的回合之前
  • 按路徑參考大型檔案而不是貼上其內容，以便 Claude 可以分塊讀取它們
  • 對於影像，請參閱下面的影像過大

影像過大

貼上或附加的影像超過了 API 的大小或尺寸限制。

Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed size

{/* min-version: 2.1.142 */}Claude Code 將無法處理的影像替換為文字佔位符並重試，因此後續訊息會成功。在 2.1.142 之前的版本上，貼上的影像可能會保留在對話中，並在每個後續訊息上重複相同的錯誤。若要在這些版本上恢復，請按 Esc 兩次並回溯到添加影像的回合之前。

該怎麼做：

  • 在貼上之前調整影像大小。API 接受單個影像最長邊最多 8000 像素的影像，或當許多影像在上下文中時為 2000 像素。
  • 拍攝相關區域的更緊密螢幕截圖，而不是整個螢幕

無法調整影像大小

Claude Code 無法在將附加影像發送到 API 之前將其縮小。

Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.
Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.
Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

Claude Code 通常會自動調整大型影像的大小。這些錯誤意味著原生影像處理器無法載入或返回錯誤，因此無法調整影像大小以符合 API 限制。

該怎麼做：

  • 如果訊息要求您轉換影像，請將其轉換為 PNG、JPEG、GIF 或 WebP，然後再次附加。Claude Code 可以驗證這些格式的尺寸，無需影像處理器。
  • 如果訊息報告尺寸或大小限制，請在附加之前將影像調整或重新壓縮到該限制以下。

PDF 錯誤

您附加的 PDF 無法處理。

PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.
PDF is password protected. Try removing protection or extracting text first.
The PDF file was not valid. Try converting to a different format first.

該怎麼做：

  • 對於超大 PDF，請要求 Claude 使用 Read 工具讀取頁面範圍，而不是附加整個檔案，或使用 pdftotext 之類的工具提取文字並按路徑參考輸出檔案
  • 對於受保護或無效的 PDF，移除密碼或從其源應用程式重新匯出檔案，然後重試

不允許額外輸入

Claude Code 和 API 之間的代理或 LLM 閘道移除了 anthropic-beta 請求標頭，因此 API 拒絕了依賴它的欄位。

API Error: 400 ... Extra inputs are not permitted ... context_management
API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples
API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

Claude Code 發送測試版專用欄位，例如 context_management、effort 和工具 input_examples，以及啟用它們的 anthropic-beta 標頭。當閘道轉發主體但移除標頭時，API 會看到它不認識的欄位。

該怎麼做：

  • 配置您的閘道以轉發 anthropic-beta 標頭。請參閱功能傳遞以了解閘道必須轉發的內容。
  • 作為備選方案，在啟動前設定 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。這會停用需要測試版標頭的功能，以便請求通過無法轉發它的閘道成功。

選定的模型有問題

配置的模型名稱未被識別，或您的帳戶缺乏對其的存取權限。從 v2.1.160 開始，尾部提示（此處以其互動形式顯示）因表面而異。

There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.

該怎麼做：

  • 互動式 CLI：執行 /model 以從您帳戶可用的模型中選擇。
  • 非互動模式 (-p)：使用有效的別名或 ID 傳遞 --model，或設定 ANTHROPIC_MODEL。錯誤文字在此表面上顯示 Run --model。
  • Agent SDK：錯誤文字省略提示，因為模型是以程式設計方式設定的。在 TypeScript 中設定 Options 上的 model，或在 Python 中設定 ClaudeAgentOptions(model=...)，並處理結構化的 model_not_found 錯誤以呈現您自己的重試或模型選擇器。
  • 使用別名（例如 sonnet 或 opus）而不是完整的版本化 ID。別名解析為維護的預設值，因此不會過時。請參閱模型配置。
  • 如果 CLI 中一直出現錯誤的模型，則某處設定了過時的 ID。按優先順序檢查：--model 標誌、ANTHROPIC_MODEL 環境變數，然後是 .claude/settings.local.json 中的 model 欄位、您專案的 .claude/settings.json 和 ~/.claude/settings.json。移除過時的值，Claude Code 會回退到您的帳戶預設值。
  • 對於 Google Cloud 的 Agent Platform 部署，請參閱 Google Cloud 的 Agent Platform 故障排除。

模型不是公認的模型 ID

您傳遞給模型切換的模型字串不是模型別名、此 Claude Code 版本知道的模型 ID，也不是以 claude- 開頭的 ID。常見原因是 ID 中的拼寫錯誤、顯示名稱（例如 Sonnet 5，其中需要 ID claude-sonnet-5），或只有較新 Claude Code 版本識別的別名。Claude Code 立即拒絕切換。在 v2.1.200 之前，Claude Code 會儲存字串並在下一個請求時失敗，出現選定的模型有問題。

Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

尾部提示命名最接近的匹配別名或模型 ID。當沒有足夠接近的內容時，它會改為讀取 Run /model to see available models.。

Claude Code 在請求切換時在本地產生此錯誤，在發出任何 API 請求之前。它適用於通過 Agent SDK setModel() 方法或為您執行 Claude Code CLI 的應用程式（例如 Desktop 應用程式）設定模型的情況。

該怎麼做：

  • 執行不帶引數的 /model 以開啟選擇器並從您帳戶可用的模型中選擇，然後傳遞那裡顯示的別名或 ID
  • 如果您使用了較新 Claude Code 版本支援的別名，請執行 claude update。以 claude- 開頭的完整 ID 即使模型比您的 Claude Code 版本更新，也會通過此檢查，因此不需要升級。
  • v2.1.200 之前儲存的模型不會被此檢查修復。如果過時的值一直出現，請從選定的模型有問題下列出的位置移除它。
  • 檢查僅在 Anthropic API 上執行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、AWS 上的 Claude Platform 和 LLM 閘道後面或自訂 ANTHROPIC_BASE_URL，您的提供者或閘道定義模型名稱，因此 Claude Code 接受任何字串並將其傳遞。

Claude Opus 不適用於 Claude Pro 方案

您的有效訂閱方案不包括您選擇的模型。

Claude Opus is not available with the Claude Pro plan · Select a different model in /model

該怎麼做：

  • 執行 /model 並選擇您的方案包括的模型
  • 如果您最近升級了方案但仍然看到此訊息，請執行 /logout 然後 /login。儲存的令牌反映您登入時的方案，因此在現有工作階段中在網路上升級不會生效，直到您重新驗證。
  • 請參閱 claude.com/pricing 以了解每個方案包括哪些模型

模型受您組織的設定限制

您的組織管理員已在 claude.ai 管理控制台中停用此模型，或它被託管設定中的 availableModels 允許清單排除。當使用 --model、ANTHROPIC_MODEL 或 model 設定設定受限制的模型時，Claude Code 會替換為允許的模型並繼續。為受限制的模型鍵入 /model <name> 會被拒絕，顯示 Run /model to choose a different model.，工作階段保持其目前模型。

Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

Claude Code 將模型系列別名（opus、sonnet、haiku 或 fable 之一）視為對該系列的請求，而不是對其最新版本的請求。在 Anthropic API 和 AWS 上的 Claude Platform 上，受限制的系列別名解析為您的組織和 availableModels 允許清單允許的系列的最新版本，替換通知命名該版本。Claude Code 僅在系列的每個版本都受限制時才拒絕 /model <alias>。在 v2.1.205 之前，系列別名是根據其最新版本單獨替換或拒絕的，即使同一系列的較舊版本被允許。

該怎麼做：

  • 執行 /model 以從您的組織允許的模型中選擇。受限制的模型在選擇器中隱藏。
  • 如果受限制的模型是在 --model、ANTHROPIC_MODEL 或設定檔案的 model 欄位中設定的，請移除或更新該值，以便通知不會在每次啟動時重複出現
  • 如果您需要存取受限制的模型，請要求您的組織管理員啟用它。請參閱組織模型限制。

此模型不支援 thinking.type.enabled

您的 Claude Code 版本比 Sonnet 5、Opus 4.8 或 Opus 4.7 的最低版本更舊。CLI 發送了模型不再接受的思考配置。

API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

該怎麼做：

  • 執行 claude update 並重新啟動 Claude Code。Opus 4.7 需要 v2.1.111 或更新版本。Opus 4.8 需要 v2.1.154 或更新版本。Sonnet 5 需要 v2.1.197 或更新版本
  • 如果您無法升級，請執行 /model 並改為選擇 Opus 4.6 或 Sonnet 4.6
  • {/* min-version: agent-sdk@0.3.197 */}如果您在 Agent SDK 中遇到此問題，請改為升級 SDK 套件。Opus 4.8 需要 TypeScript SDK v0.3.154 或更新版本和 Python SDK v0.2.88 或更新版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更新版本

思考預算超過輸出限制

配置的擴展思考預算超過最大回應長度，因此沒有空間留給實際答案。

API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

Claude Code 在 Anthropic API 上自動調整這些值。當 MAX_THINKING_TOKENS 設定高於提供者的輸出限制時，或當計畫模式提高思考預算時，您通常會在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此錯誤。

該怎麼做：

工具使用或思考區塊不匹配

對話歷史以不一致的狀態到達 API，通常是在工具呼叫被中斷或回合在中途被編輯後。

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks
API Error: 400 ... thinking blocks ... cannot be modified

所有三個變體都意味著同一件事：歷史中 tool_use、tool_result 和 thinking 區塊的序列不再與 API 期望的相符。

該怎麼做：

  • {/* max-version: 2.1.155 */}如果您使用的是 Opus 4.7 或 Opus 4.8，請先執行 claude update。v2.1.156 之前的版本可能在正常工具使用期間觸發此錯誤，而 /rewind 不會清除它。
  • 執行 /rewind 或按 Esc 兩次，以回溯到損壞回合之前的檢查點並從那裡繼續。請參閱檢查點以了解如何建立和恢復檢查點。

使用政策拒絕

API 拒絕回應，因為對話中的內容觸發了使用政策檢查。訊息包括您可以引用給支援的請求 ID，如果您認為拒絕不正確。

API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.

檢查評估完整對話，而不僅是您的最新提示，因此在同一工作階段中發送新訊息通常會重新觸發相同的拒絕。在使用 --continue 或 --resume 退出並重新開啟工作階段後也是如此，因為磁碟上的文字記錄仍然包含觸發內容。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，此訊息也涵蓋模型的安全措施標記為網路安全主題的請求。請參閱安全措施標記了網路安全主題。

該怎麼做：

  • 按 Esc 兩次或執行 /rewind 以回溯到觸發拒絕的回合之前的檢查點，然後重新表述或採取不同的方法。請參閱檢查點。
  • 如果您無法識別哪個回合導致了它，請執行 /clear 以在同一專案中開始新的對話。您之前的對話會保留在磁碟上，並在 /resume 中保持可用。
  • 在非互動模式(-p) 中，其中無法進行倒帶，請在沒有 --continue 的新工作階段中使用重新表述的提示重試。政策檢查因模型而異，因此使用 --model 切換到不同的模型也可能在某些情況下解決拒絕。

安全措施標記了網路安全主題

模型的安全措施將對話中的內容標記為網路安全主題。訊息命名標記請求的模型：

API Error: Opus 4.8 has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude.

If you were not engaging in a cybersecurity topic, please send feedback via /feedback.

訊息連結到網路安全驗證計畫，該計畫為合法網路安全工作授予存取權限。保護措施本身是伺服器端的，早於 v2.1.203；此版本僅更改了訊息的措辭和它連結到的頁面。

您看到的內容取決於您的提供者和模式：

{/* max-version: 2.1.202 */}在 v2.1.203 之前，訊息讀取 <model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption: 後跟豁免表單連結。

該怎麼做：

  • 如果您的工作需要此內容，請通過網路安全驗證計畫申請存取權限
  • 如果您的請求不是關於網路安全主題，請執行 /feedback 以報告誤報
  • 若要在同一工作階段中繼續工作，請按 Esc 兩次或執行 /rewind 以回溯到觸發標記的回合之前的檢查點，然後採取不同的方法。請參閱檢查點。

安裝錯誤

這些錯誤會在安裝或更新 Claude Code 時出現，來自 安裝指令碼、claude install 或 claude update。如需 command not found、PATH、權限和設定期間的 TLS 問題，請參閱 疑難排解安裝和登入。

安裝在完成前被中止

當 claude install 步驟被信號終止時，安裝指令碼會報告。在 Linux 上，結束代碼 137 表示程序收到 SIGKILL，在低記憶體主機上，通常是核心記憶體不足 (OOM) 殺手。指令碼會列印此說明並以代碼 137 結束：

Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

對於任何其他致命信號，以及 macOS 上的結束代碼 137，指令碼會列印 Installation was killed before it could finish (exit code <N>)，其中包含實際結束代碼，並省略記憶體不足的說明。該訊息來自 macOS 和 Linux 使用的安裝指令碼，也涵蓋 WSL 內的安裝；原生 Windows 安裝指令碼永遠不會列印它。在 v2.1.200 之前，指令碼只以 shell 的裸 Killed 行結束。

該怎麼做：

下載更新時連線中斷

當 claude install、claude update 或 自動更新程式 正在擷取 Claude Code 二進位檔案時，與下載伺服器的連線已關閉，且重試未能恢復。當連線中斷、傳輸停滯或下載的檔案未通過校驗和時，Claude Code 會重試下載，最多嘗試三次。已完成的 HTTP 錯誤（例如 404）不會重試，因為伺服器已經回應。{/* min-version: 2.1.202 */}在 v2.1.202 之前，單一連線中斷會立即導致下載失敗，並顯示裸錯誤 aborted，而不是重試。

The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

括號中的文字命名失敗的嘗試和基礎網路錯誤。claude update 在 stderr 上以 Error: Failed to install native update 開頭該訊息。

保持連線但在 10 分鐘內未完成的下載會失敗，並顯示 Download timed out: exceeded the total deadline。Claude Code 不會重試逾時的下載，因為連線速度太慢而無法在期限內完成，在立即重試時也不會完成。下面的步驟適用於兩個訊息。在 v2.1.205 之前，相同的 10 分鐘期限被報告為 HTTP 用戶端的通用 timeout of 600000ms exceeded。

通常的原因是代理或閘道在傳輸完成前關閉長傳輸。Claude Code 二進位檔案是大型下載，因此永遠不會影響正常 API 流量的代理連線限制仍然可能中斷它。

該怎麼做：

  • 再次執行 claude update。在網路狀況良好的情況下，下載通常在下次執行時成功。對於逾時訊息，請從更快或限制較少的網路重新執行。
  • 如果您的網路需要代理，請在執行安裝程式或 claude update 之前設定 HTTPS_PROXY。請參閱 檢查網路連線。
  • 如果公司代理持續關閉傳輸，請要求您的網路團隊允許從 downloads.claude.ai 進行完整下載。請參閱 網路存取需求。
  • 從您的 shell 執行 claude doctor 以進行安裝診斷

命令列錯誤

這些錯誤來自 claude 命令列及其子命令。Claude Code 在執行您的提示或傳送任何 API 請求之前會列印這些錯誤。

\--bg 和 --print 之間的衝突

此訊息需要 Claude Code v2.1.198 或更新版本。您在同一個 claude 呼叫中結合了 --bg 與 -p 或 --print。--bg 啟動一個背景工作階段，您稍後可以使用 claude agents 附加到該工作階段，而 --print 以非互動模式執行，永遠不會啟動 claude agents 附加到的互動工作階段。在 v2.1.198 之前，此組合會無聲地建立一個永遠無法附加的背景工作。

--bg 和 --print 衝突：--print 永遠不會啟動 `claude agents` 附加到的互動工作階段，因此工作將無法附加。提示是位置引數 — 移除 --print：`claude --bg '<task>'`。

該怎麼做：

  • 移除 -p 或 --print。--bg 將提示作為其位置引數，所以 claude --bg "<task>" 是完整的命令。請參閱從您的 shell 分派新代理。
  • 若要以非互動模式執行提示並列印結果而不是建立背景工作階段，請移除 --bg 並執行 claude -p "<task>"

\--json-schema 值不是有效的 JSON Schema

您傳遞給--json-schema 的結構描述在非互動模式中未能通過 JSON Schema 編譯，因此 claude 以代碼 1 結束而不是執行提示。在 v2.1.205 之前，無效的結構描述會產生無結構的輸出且沒有錯誤，任何使用 format 關鍵字的結構描述都被視為無效。

Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

第二個冒號之後的文字是驗證器的診斷，並命名失敗的關鍵字或位置。使用 format 關鍵字的結構描述（例如 "format": "email"）是有效的：Claude Code 接受 format 作為註解，不強制執行它。

Claude Code 在結構描述編譯之前執行兩項檢查：它拒絕不可解析的 JSON 值，並顯示 Error: --json-schema is not valid JSON，以及有效但不是物件的 JSON，並顯示 Error: --json-schema must be a JSON object。

該怎麼做：

  • 修復診斷命名的結構描述部分，然後重新執行命令
  • 如果診斷是 schema too large，請減少結構描述的巢狀和 $ref 重複使用
  • 請參閱取得結構化輸出以取得有效的結構描述和命令

無法從 Claude Desktop 匯入伺服器

Claude Code 無法新增您在 claude mcp add-from-claude-desktop 中選擇的其中一個伺服器。該命令仍會匯入其他選定的伺服器，並為每個無法新增的伺服器列印一行。在 v2.1.205 之前，第一個失敗的伺服器會停止匯入，且所有選定的伺服器都不會被新增。

Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

伺服器名稱之後的文字是原因。最常見的是名稱檢查：Claude Desktop 允許伺服器名稱中的字元（例如空格和句號），而 claude mcp 限制為字母、數字、連字號和底線。其他原因包括未通過驗證的伺服器配置，以及被您組織的 MCP 政策阻止的伺服器。

該怎麼做：

  • 在 claude_desktop_config.json 中重新命名伺服器，僅使用字母、數字、連字號和底線，然後再次執行 claude mcp add-from-claude-desktop
  • 使用 claude mcp add 或 claude mcp add-json 在有效名稱下直接新增該伺服器。請參閱從 Claude Desktop 匯入 MCP 伺服器。

外掛程式錯誤

這些錯誤來自 外掛程式 和 marketplace 設定。對於不會產生此頁面上其中一則訊息的外掛程式問題，例如無法載入的 marketplace URL 或已安裝但未出現的外掛程式，請參閱 外掛程式疑難排解。

Marketplace 是從不受信任的來源註冊的

Marketplace 是以 為官方 Anthropic marketplace 保留的名稱 註冊的，但其註冊的來源不是 anthropics GitHub 儲存庫。Claude Code 每次載入或重新整理 marketplace 時都會重新檢查保留的名稱，因此 marketplace 和從中安裝的外掛程式會停止載入。在 v2.1.205 之前，名稱只在新增 marketplace 時檢查，因此在其名稱變成保留名稱之前註冊的項目會繼續載入。

Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

該怎麼做：

  • 執行 claude plugin marketplace remove <name>，然後從官方 github.com/anthropics 儲存庫重新新增 marketplace
  • 如果您發佈了在名稱變成保留名稱之前使用該名稱的第三方 marketplace，請重新命名它並要求使用者從您的來源重新新增它
  • 請參閱 Marketplace schema 下的保留名稱清單

設定警告

Claude Code 在啟動時將這些訊息寫入 stderr，而不是在對話中顯示錯誤。它們報告 Claude Code 讀取但未應用的設定。

工作區尚未受信任

Claude Code 在專案的 .claude/settings.json 或 .claude/settings.local.json 中找到 permissions.allow 規則或 permissions.additionalDirectories 項目，但未應用它們，因為來自專案設定的允許規則需要工作區信任。訊息中的計數、設定名稱和檔案名稱會根據您的設定而異。deny 和 ask 規則不受影響。

Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

該怎麼做：

  • 在目錄中執行 claude 並接受信任對話框。{/* min-version: 2.1.200 */}即使父目錄已受信任，對話框仍會出現，列出被保留的規則，並讓您拒絕並繼續工作而不使用它們。在 v2.1.200 之前，在該情況下不會出現對話框，因此無法在那裡完成此步驟。
  • 在非互動模式中使用 -p 不會顯示對話框。使用訊息列印的確切 projects 金鑰在 ~/.claude.json 中設定 hasTrustDialogAccepted 項目。
  • {/* min-version: 2.1.200 */}如果訊息命名 .claude/settings.local.json 且您在 git 儲存庫外或主目錄中啟動 Claude Code，請更新至 v2.1.200 或更新版本。版本 2.1.196 至 2.1.199 在這些工作區中將您自己的 .claude/settings.local.json 視為儲存庫提供的。請參閱專案允許規則和工作區信任。

回應品質似乎低於預期

如果 Claude 的回答似乎不如預期那樣有能力，但沒有顯示錯誤，原因通常是對話狀態而非模型本身。Claude Code 不會無聲地更改模型版本。它只能在三種特定情況下切換到備用模型：

  • 配置的 --fallback-model 在可用性錯誤後接管該輪次，並在文字記錄中顯示通知
  • Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用
  • 自動模型備用在 Fable 5 上將工作階段移至預設 Opus 模型，並在文字記錄中顯示通知

下面的模型選擇檢查會捕捉第二和第三種情況；第一種情況會顯示為文字記錄通知而非 /model 變更。模型配置說明每種備用何時適用。

首先檢查這些項目：

  • 模型選擇：執行 /model 以確認您使用的是預期的模型。先前的 /model 選擇或 ANTHROPIC_MODEL 環境變數可能會讓您使用比預期更小的模型。
  • 努力程度：執行 /effort 以檢查目前的推理程度，並針對困難的除錯或設計工作提高它。預設值因模型而異，因此在假設您低於最大值之前請先檢查。請參閱調整努力程度以了解各模型的預設值和 ultrathink 快捷方式。
  • 上下文壓力：執行 /context 以查看視窗的滿度。如果接近容量，請在自然中斷點執行 /compact 或執行 /clear 以重新開始。請參閱探索上下文視窗以了解自動壓縮如何影響較早的輪次。
  • 過時的指示：大型或過時的 CLAUDE.md 檔案和 MCP 工具定義會消耗上下文，並可能引導回應。{/* min-version: 2.1.205 */}/doctor 檢查會標記超大的記憶體檔案和未使用的擴充功能，/context 會顯示 MCP 工具的權杖使用情況。在 v2.1.205 之前，/doctor 會開啟診斷畫面，標記超大的記憶體檔案和子代理定義。

當回應出錯時，通常比用更正回覆更有效的做法是回溯。按 Esc 兩次或執行 /rewind 以回到不良輪次之前，然後用更具體的內容重新表述提示。在執行緒中更正會將錯誤的嘗試保留在上下文中，這可能會將後續答案錨定到它。請參閱檢查點。

如果在檢查上述項目後品質仍然似乎不對，請執行 /feedback 並描述您預期的內容與實際得到的內容。以這種方式提交的回饋包括對話文字記錄，這是 Anthropic 診斷真實迴歸的最快方式。如果 /feedback 在您的環境中不可用，請參閱報告錯誤。

{/* min-version: 2.1.201 */}如果 Sonnet 5 拒絕請求並在 Claude Code v2.1.200 或更早版本上引用可疑的提示注入，請執行 claude update 以取得 v2.1.201 修正。

回報錯誤

如需了解此頁面未涵蓋的元件錯誤，請參閱相關指南：

如果此處未列出錯誤或建議的修正方法無法幫助：

  • 在 Claude Code 內執行 /feedback 以將文字記錄和說明傳送給 Anthropic。該命令也提供開啟預先填入的 GitHub issue 的選項。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供者上，/feedback 會儲存本機封存，您可以將其傳送給您的 Anthropic 帳戶代表。
  • 從您的 shell 執行 claude doctor 以進行安裝的唯讀診斷，或在 Claude Code 內執行 /doctor 檢查以尋找並修正設定問題
  • 檢查 status.claude.com 以了解活躍的事件
  • 在 GitHub 上搜尋現有 issue