错误处理

Claude Code 是一个长时间运行的网络进程，它与 Anthropic API 通信、执行 shell 命令、读取和写入文件以及管理子代理 — 所有这些都可能失败。 代码库不会让错误任意传播，而是具有分层错误架构，可以对故障进行分类，决定是否重试或显示错误，并确保用户始终看到有意义的消息。

错误堆栈中有四个不同的层：

每个主要故障模式都有自己的命名类别。 这不仅仅是风格——它让呼叫者可以使用 instanceof 检查在生产版本中是否可以进行缩小和类名修改。

The isAbortError 三向检查

中止信号来自三个不同的源，具体取决于上下文，并且它们的类名在生产版本中被破坏。 助手守护着这三个人：

export function isAbortError(e: unknown): boolean {
  return (
    e instanceof AbortError ||           // our own class
    e instanceof APIUserAbortError ||    // SDK's class — checked by instanceof
    (e instanceof Error && e.name === 'AbortError')  // DOMException from AbortController
  )
}

实用助手——捕获点边界

而不是铸造 unknown to Error 在任何地方，一小组函数都会对边界处的 catch 值进行标准化：

// Normalize unknown → Error (use at catch-site when you need an Error instance)
export function toError(e: unknown): Error {
  return e instanceof Error ? e : new Error(String(e))
}

// Only need the message string (for logging, display)
export function errorMessage(e: unknown): string {
  return e instanceof Error ? e.message : String(e)
}

// Trim stack to top-N frames so tool_result payloads don't waste tokens
export function shortErrorStack(e: unknown, maxFrames = 5): string {
  if (!(e instanceof Error)) return String(e)
  if (!e.stack) return e.message
  const lines = e.stack.split('\n')
  const header = lines[0] ?? e.message
  const frames = lines.slice(1).filter(l => l.trim().startsWith('at '))
  if (frames.length <= maxFrames) return e.stack
  return [header, ...frames.slice(0, maxFrames)].join('\n')
}

文件系统错误助手

Node.js 文件系统错误带有 errno 错误对象上的代码，但 TypeScript 将其键入为 any。 代码库用类型化助手替换了不安全的转换模式：

// Safe alternative to (e as NodeJS.ErrnoException).code
export function getErrnoCode(e: unknown): string | undefined

// Covers: ENOENT | EACCES | EPERM | ENOTDIR | ELOOP
export function isFsInaccessible(e: unknown): e is NodeJS.ErrnoException

isFsInaccessible 涵盖五个 errno 代码，因为当尝试访问路径（名为的文件）时，它们中的任何一个都可能出现 .claude 预期目录的位置会触发 ENOTDIR; 循环符号链接给出 ELOOP。 仅检查 ENOENT 会想念这些。

遥测安全纪律

TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS 是故意长的。 该名称迫使开发人员在使用之前有意识地承认错误消息不包含敏感数据。 使用两个参数的形式，您可以向用户记录完整消息（带有文件路径），同时将经过清理的版本发送到遥测：

// Two-arg form: full message for user, scrubbed for telemetry
throw new TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS(
  `MCP tool timed out after ${ms}ms`,  // full message
  'MCP tool timed out'              // telemetry message (no timing data)
)

当一个工具失败时，它的错误必须针对两个消费者进行格式化：终端（对于用户）和模型（在一个 tool_result block). toolErrors.ts 处理这两个问题，包括带有中心截断的硬性 10,000 个字符上限，以保护上下文预算。

export function formatError(error: unknown): string {
  if (error instanceof AbortError) {
    return error.message || INTERRUPT_MESSAGE_FOR_TOOL_USE
  }
  if (!(error instanceof Error)) return String(error)
  const parts = getErrorParts(error)
  const fullMessage = parts.filter(Boolean).join('\n').trim()
    || 'Command failed with no output'
  if (fullMessage.length <= 10000) return fullMessage

  // Center-truncate: keep head + tail of large outputs
  const halfLength = 5000
  return `${fullMessage.slice(0, halfLength)}\n\n...${fullMessage.length - 10000} characters truncated...\n\n${fullMessage.slice(-halfLength)}`
}

For ShellError，各部分按优先级顺序组装：首先退出代码，然后是 stderr，然后是 stdout。 这反映了开发人员希望看到的内容——首先是最具诊断性的信息。

Zod 验证错误 → LLM 友好消息

当模型调用具有错误架构的工具时， ZodError 转换为模型可以理解和纠正的结构化英语消息：

// Input: ZodError with two issues — missing param + wrong type
// Output:
"FileEditTool failed due to the following issues:
The required parameter `old_string` is missing
The parameter `new_string` type is expected as `string` but provided as `number`"

错误日志记录通过接收器模式与实际写入实现分离。 log.ts 是无依赖性的——它对事件进行排队，直到连接了接收器。 errorLogSink.ts 包含繁重的实现（文件 I/O、axios 丰富），并在启动期间初始化一次。

接收器将错误作为 JSONL（每行一个 JSON 对象）写入带日期标记的文件。 每个条目包括时间戳、会话 ID、cwd 和版本。 对于 axios 错误，它会提取请求 URL、HTTP 状态和服务器错误正文——这三个字段对于诊断 API 问题最有用。

// Buffered JSONL writer — flushes every 1 second or after 50 entries
// On first write: mkdirSync creates parent dirs, then appendFileSync
// Registered with cleanupRegistry so it flushes on process exit
function createJsonlWriter(options: {
  writeFn: (content: string) => void
  flushIntervalMs?: number     // default: 1000
  maxBufferSize?: number        // default: 50
}): JsonlWriter

withRetry 是一个包装每个 Anthropic API 调用的异步生成器。 它实现了复杂的重试策略，可以处理瞬时网络故障、速率限制、身份验证令牌过期、上下文溢出和 Claude 特定的 529 过载状态。

重试延迟公式

当许多客户端同时达到速率限制时，退避使用具有 ±25% 抖动的指数延迟来避免惊群：

export function getRetryDelay(
  attempt: number,
  retryAfterHeader?: string | null,
  maxDelayMs = 32000,
): number {
  if (retryAfterHeader) {
    const seconds = parseInt(retryAfterHeader, 10)
    if (!isNaN(seconds)) return seconds * 1000  // honor server directive
  }
  const baseDelay = Math.min(
    500 * Math.pow(2, attempt - 1),   // 500ms, 1s, 2s, 4s... cap 32s
    maxDelayMs,
  )
  const jitter = Math.random() * 0.25 * baseDelay
  return baseDelay + jitter
}

529重载错误——特殊处理

HTTP 529 是 Claude 特定的状态代码，表示 API 过载。 它有自己的逻辑，因为：

• 后台查询源（标题生成器、摘要生成器）立即退出 - 在容量事件期间从数十个客户端重试会放大级联
• 在 Opus 模型上连续 3 个 529 后，引擎通过以下方式回退到配置的后备模型 FallbackTriggeredError
• SDK 有时无法设置 status=529 流式传输期间 — 后备检查 error.message.includes('"type":"overloaded_error"')

export function is529Error(error: unknown): boolean {
  if (!(error instanceof APIError)) return false
  return (
    error.status === 529 ||
    // SDK streaming bug: status not set, check message content
    (error.message?.includes('"type":"overloaded_error"') ?? false)
  )
}

上下文溢出自动调整

当请求被拒绝且输入长度为 400" 时 max_tokens 超出上下文限制”错误， withRetry 解析消息中的令牌计数并自动减少 maxTokens 进行下一次尝试 - 无需任何用户操作：

// Error message format:
// "input length and `max_tokens` exceed context limit: 188059 + 20000 > 200000"

// Auto-adjustment:
const availableContext = Math.max(0, contextLimit - inputTokens - 1000) // safety buffer
retryContext.maxTokensOverride = Math.max(FLOOR_OUTPUT_TOKENS, availableContext, minRequired)

持久重试模式（CLAUDE_CODE_UNATTENDED_RETRY)

对于无人值守/CI 会话，设置 CLAUDE_CODE_UNATTENDED_RETRY=1 允许无限期重试 429/529，最大退避时间为 5 分钟，总上限为 6 小时。 长时间的等待被分成 30 秒的心跳产量，因此主机环境（CI 运行程序，tmux 会话）不会将进程标记为空闲。

所有用户可见的错误字符串都定义为一个文件中的命名常量。 这使得它们可搜索、可测试，并防止抛出位置和检测位置之间的消息漂移：

export const INVALID_API_KEY_ERROR_MESSAGE = 'Not logged in · Please run /login'
export const TOKEN_REVOKED_ERROR_MESSAGE    = 'OAuth token revoked · Please run /login'
export const REPEATED_529_ERROR_MESSAGE     = 'Repeated 529 Overloaded errors'
export const API_TIMEOUT_ERROR_MESSAGE      = 'Request timed out'
export const CREDIT_BALANCE_TOO_LOW_ERROR_MESSAGE = 'Credit balance is too low'

交互式会话与非交互式会话针对媒体错误获得不同的指导。 相同 getImageTooLargeErrorMessage() 函数为 REPL 用户返回“双击 esc 返回”，为 SDK/无头调用者返回“尝试调整图像大小”：

export function getImageTooLargeErrorMessage(): string {
  return getIsNonInteractiveSession()
    ? 'Image was too large. Try resizing the image or using a different approach.'
    : 'Image was too large. Double press esc to go back and try again with a smaller image.'
}

当未处理的异常到达 Ink 渲染树时， ErrorOverview 直接在终端中显示它——不是堆栈转储，而是带有崩溃位置和内联源上下文的格式化覆盖层。 它使用两个库： StackUtils 解析 V8 堆栈帧，以及 code-excerpt 读取并显示相关源代码行。

// 1. Parse the first stack frame to get file + line + column
const stack = error.stack ? error.stack.split('\n').slice(1) : undefined
const origin = stack ? getStackUtils().parseLine(stack[0]!) : undefined

// 2. Read source file synchronously (sync OK: error overlay, can't go async)
const sourceCode = readFileSync(filePath, 'utf8')
excerpt = codeExcerpt(sourceCode, origin.line)

// 3. Render: crash line is highlighted in red; surrounding lines are dim
const isCrashLine = line_0 === origin.line
<Text
  backgroundColor={isCrashLine ? 'ansi:red' : undefined}
  color={isCrashLine ? 'ansi:white' : undefined}
  dim={!isCrashLine}
>
  {' ' + value}
</Text>

如果源文件不可读（例如，进程移动了工作目录或文件被删除），则 readFileSync 被包裹在一片寂静之中 try/catch。 覆盖层会优雅地降级 - 它仍然显示错误消息和完整解析的堆栈，只是没有源代码摘录。

The SentryErrorBoundary

Alongside ErrorOverview，有一个 React 错误边界 components/SentryErrorBoundary.ts。 它捕获来自任何子组件的渲染错误并渲染 null （无声失败）而不是使整个 Ink 树崩溃：

export class SentryErrorBoundary extends React.Component<Props, State> {
  static getDerivedStateFromError(): State {
    return { hasError: true }
  }

  render(): React.ReactNode {
    if (this.state.hasError) return null  // silent: don't crash the whole UI
    return this.props.children
  }
}

当 Claude Code 中途崩溃或被强制终止时，磁盘上的对话记录可能会处于不一致的状态。 conversationRecovery.ts 负责加载、清理转录本并将其恢复为可恢复状态。

四阶段反序列化管道

deserializeMessagesWithInterruptDetection 通过四个过滤器运行原始持久消息，然后将它们传回 REPL：

中断分类

过滤后，最后一条“回合相关”消息（跳过 system, progress和 API 错误助手）确定发生了什么：

// Last message is an assistant → turn completed normally
if (lastMessage.type === 'assistant') return { kind: 'none' }

// Last message is a plain user prompt → CC hadn't started responding
if (lastMessage.type === 'user' && !isToolUseResultMessage(lastMessage))
  return { kind: 'interrupted_prompt', message: lastMessage }

// Last message is a tool_result → AI was mid-tool-use
if (isToolUseResultMessage(lastMessage)) {
  // Special case: brief mode ends on SendUserMessage tool_result legitimately
  if (isTerminalToolResult(lastMessage, messages, lastMessageIdx))
    return { kind: 'none' }
  return { kind: 'interrupted_turn' }
}

综合连续消息

An interrupted_turn （AI被杀时处于中间工具状态）转换为 interrupted_prompt 通过注射合成物 “从上次停下的地方继续。” 用户留言。 这统一了两种中断类型，因此消费者只需要处理一种情况：

if (internalState.kind === 'interrupted_turn') {
  const [continuationMessage] = normalizeMessages([
    createUserMessage({ content: 'Continue from where you left off.', isMeta: true })
  ])
  filteredMessages.push(continuationMessage!)
  turnInterruptionState = { kind: 'interrupted_prompt', message: continuationMessage! }
}

API 有效哨兵

如果所有过滤后的最后一条相关消息是用户消息，则 Anthropic API 将拒绝该对话（该对话必须在助理轮流进行流式传输时结束）。 一种合成的 NO_RESPONSE_REQUESTED Assistant Sentinel 拼接在用户消息之后，因此即使不采取恢复操作，对话也始终是 API 有效的。

技能状态恢复

反序列化之前， restoreSkillStateFromMessages 行走的成绩单 invoked_skills 附件并在进程状态中重新注册这些技能。 如果没有这个，恢复后的第二次压缩将失去对哪些技能处于活动状态的跟踪：

for (const message of messages) {
  if (message.attachment?.type === 'invoked_skills') {
    for (const skill of message.attachment.skills) {
      addInvokedSkill(skill.name, skill.path, skill.content, null)
    }
  }
  // Suppress re-sending skill listing if already in transcript
  if (message.attachment?.type === 'skill_listing') suppressNextSkillListing()
}